@banou/media-player 0.8.1 → 0.8.3

package/dist/react/components/chrome.d.ts

@@ -4,7 +4,7 @@ export type ChromeProps = {
     /** Absent means render no video element: the media belongs to someone else and arrives as children. */
     onVideoRef?: (element: HTMLVideoElement | null) => void;
     onCanvasRef: (element: HTMLCanvasElement | null) => void;
-    /** Above the control bar and outside the click-to-pause region, unlike `children`. */
+    /** The app's own content, over the video and outside the click-to-pause region, unlike `children`. */
     overlay?: ReactNode;
     children?: ReactNode;
 };

package/dist/react/video-player.d.ts

@@ -17,8 +17,26 @@ type CommonOptions = {
     title?: string;
     autoplay?: boolean;
     /**
-     * Drawn above the control bar and outside the click-to-pause region, for whatever the app has to
-     * say over the video. `children` land next to the media instead, below the chrome.
+     * 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;
     onSeek?: (fraction: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "A video player for containers and codecs the browser cannot play natively, remuxed on the fly",
   "type": "module",
   "main": "dist/index.js",

package/src/lib/react/components/chrome.tsx

@@ -1,7 +1,7 @@
 /// <reference types="@emotion/react/types/css-prop" />
 import type { ReactNode, Ref } from 'react'
 
-import { useEffect, useRef } from 'react'
+import { Children, Fragment, isValidElement, useEffect, useRef } from 'react'
 import { css } from '@emotion/react'
 
 import { usePlayer } from '../player'
@@ -10,6 +10,30 @@ import ControlBar from './control-bar'
 
 const AUTO_HIDE_DELAY = 3_000
 
+/**
+ * One overlay item's own layer: the whole player box, and nothing else in it.
+ *
+ * The box is what makes an item positionable at all. Dropped straight into the chrome an item is
+ * absolutely positioned with no inset, which resolves to its static position, and the chrome centres
+ * its children, so a download readout came out painted across the middle of the picture. With this
+ * the app writes ordinary CSS against the picture: `top: 0; right: 0` is the top right corner of the
+ * video and of nothing else.
+ *
+ * One layer per item rather than one for all of them, so an item's own CSS can never move a sibling.
+ */
+const overlayItemStyle = css`
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  /* Never eats a click: click-to-pause still reaches the video underneath, and an item that needs a
+     pointer (a tooltip anchor, a button) sets \`pointer-events: auto\` on itself. */
+  pointer-events: none;
+  /* visibility, not only opacity: an item that took pointer events back would otherwise stay
+     hoverable while faded out, popping a tooltip over nothing. It cascades where pointer-events does
+     not, and transitioning it holds the item on screen for the length of the fade. */
+  transition: opacity 0.1s cubic-bezier(.4,0,1,1), visibility 0.1s;
+`
+
 const style = css`
   position: relative;
   background-color: black;
@@ -44,12 +68,32 @@ const style = css`
   }
 `
 
+/**
+ * The overlay's top-level items, one entry per layer to draw.
+ *
+ * `Children.toArray` alone is not enough. It flattens an ARRAY and keys what it returns, but a
+ * fragment stays one child, and `<>{a}{b}</>` is the shorthand an app reaches for before it reaches
+ * for an array. Left unflattened both items land in one layer, where the first item's CSS decides
+ * where the second one goes, which is exactly what having a layer each is for.
+ *
+ * Keys are built from the path rather than taken from each level, because `Children.toArray` numbers
+ * from zero inside every call it makes: two fragments each holding one unkeyed item both hand back
+ * `.0`, and React would treat the second layer as the first one re-rendered.
+ */
+const overlayItems = (node: ReactNode, prefix = ''): { key: string, item: ReactNode }[] =>
+  Children.toArray(node).flatMap((child, index) => {
+    const key = `${prefix}${isValidElement(child) && child.key != null ? child.key : index}`
+    return isValidElement(child) && child.type === Fragment
+      ? overlayItems((child.props as { children?: ReactNode }).children, `${key}/`)
+      : [{ key, item: child }]
+  })
+
 export type ChromeProps = {
   ref?: Ref<HTMLDivElement> | ((element: HTMLDivElement | null) => void)
   /** Absent means render no video element: the media belongs to someone else and arrives as children. */
   onVideoRef?: (element: HTMLVideoElement | null) => void
   onCanvasRef: (element: HTMLCanvasElement | null) => void
-  /** Above the control bar and outside the click-to-pause region, unlike `children`. */
+  /** The app's own content, over the video and outside the click-to-pause region, unlike `children`. */
   overlay?: ReactNode
   children?: ReactNode
 }
@@ -117,7 +161,15 @@ export const Chrome = ({ ref, onVideoRef, onCanvasRef, overlay, children }: Chro
       className={hideUI ? 'hide' : ''}
     >
       <Overlay onCanvasRef={onCanvasRef} />
-      {overlay}
+      {overlayItems(overlay).map(({ key, item }) => (
+        <div
+          key={key}
+          css={overlayItemStyle}
+          style={{ ...hideUI ? { opacity: '0', visibility: 'hidden', pointerEvents: 'none' } : {} }}
+        >
+          {item}
+        </div>
+      ))}
       <ControlBar />
       <div className="video" onClick={onVideoClick}>
         {onVideoRef ? <video ref={onVideoRef} playsInline /> : null}

package/src/lib/react/components/overlay.tsx

@@ -1,4 +1,6 @@
 /// <reference types="@emotion/react/types/css-prop" />
+import type { ReactNode } from 'react'
+
 import { css, keyframes } from '@emotion/react'
 
 import { usePlayer } from '../player'
@@ -100,6 +102,7 @@ export const Overlay = ({ onCanvasRef }: { onCanvasRef: (element: HTMLCanvasElem
       {title
         ? (
           <div
+            className="title"
             css={titleStyle}
             style={{ ...hideUI ? { opacity: '0', pointerEvents: 'none' } : {} }}
           >

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

@@ -27,8 +27,26 @@ type CommonOptions = {
   autoplay?: boolean
 
   /**
-   * Drawn above the control bar and outside the click-to-pause region, for whatever the app has to
-   * say over the video. `children` land next to the media instead, below the chrome.
+   * 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
 
@@ -204,6 +222,19 @@ const rootStyle = css`
    */
   --mp-unit: 10px;
 
+  /**
+   * The other half of owning the chrome's own scale.
+   *
+   * Every control here is authored against a border box, which this library's dev app sets globally
+   * and a host page has no reason to. Shipped without it, anything that is \`width: 100%\` AND carries
+   * padding overflows its own box: the top bar ran 32px past the player and clipped the right end of
+   * whatever the app had put there. Scoped to the player's subtree so it cannot reach the host's
+   * layout, and only \`box-sizing\`, because zeroing margins here would reach the app's own content.
+   */
+  &, & *, & *::before, & *::after {
+    box-sizing: border-box;
+  }
+
   display: flex;
   justify-content: center;
   background-color: #111;