@banou/media-player 0.8.2 → 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;
-    /** The app's own content, drawn in the top bar beside the title, 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/components/overlay.d.ts

@@ -1,8 +1,4 @@
-import type { ReactNode } from 'react';
-export type OverlayProps = {
+export declare const Overlay: ({ onCanvasRef }: {
     onCanvasRef: (element: HTMLCanvasElement | null) => void;
-    /** The app's own content, drawn at the right of the top bar next to the title. */
-    overlay?: ReactNode;
-};
-export declare const Overlay: ({ onCanvasRef, overlay }: OverlayProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+}) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Overlay;

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

@@ -17,13 +17,26 @@ type CommonOptions = {
     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.
+     * The app's own content over the video: a download readout, a badge, a logo, anything the player
+     * itself has no opinion about.
      *
-     * 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.
+     * 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.2",
+  "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
-  /** The app's own content, drawn in the top bar beside the title, unlike `children`. */
+  /** The app's own content, over the video and outside the click-to-pause region, unlike `children`. */
   overlay?: ReactNode
   children?: ReactNode
 }
@@ -116,7 +160,16 @@ export const Chrome = ({ ref, onVideoRef, onCanvasRef, overlay, children }: Chro
       onMouseOut={onMouseOut}
       className={hideUI ? 'hide' : ''}
     >
-      <Overlay onCanvasRef={onCanvasRef} overlay={overlay} />
+      <Overlay onCanvasRef={onCanvasRef} />
+      {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

@@ -15,74 +15,35 @@ const style = css`
   pointer-events: none;
 `
 
-/**
- * Title on the left, the app's own readout on the right, one gradient behind both.
- *
- * They share a row rather than sitting in two layers because they are the same band of screen: a
- * filename wide enough to wrap would otherwise run under whatever the app put on the right, and two
- * stacked gradients would double the darkening.
- */
-const topBarStyle = css`
+const titleStyle = css`
   position: absolute;
   top: 0;
   left: 0;
   width: 100%;
+  padding: calc(1.2 * var(--mp-unit)) calc(1.6 * var(--mp-unit));
+  /* clears a notch once the player is fullscreen; resolves to zero everywhere else */
+  padding-top: calc(calc(1.2 * var(--mp-unit)) + env(safe-area-inset-top, 0px));
+  ${fonts.headings.small}
+  color: white;
+  text-shadow: 0 0 4px rgba(0, 0, 0, 1);
   z-index: 2;
-  /* the video underneath keeps the click that toggles playback; anything in the slot that needs a
-     pointer takes it back for itself */
   pointer-events: none;
 
-  display: flex;
-  align-items: flex-start;
-  gap: calc(1.6 * var(--mp-unit));
-
-  /* longhands per breakpoint, never the shorthand: a nested at-rule is hoisted after the rule it
-     sits in, so a shorthand in a media query would override the longhands above it and silently
-     drop the safe-area insets. Those clear a notch once the player is fullscreen and resolve to
-     zero everywhere else. */
-  padding-top: calc(calc(1.2 * var(--mp-unit)) + env(safe-area-inset-top, 0px));
-  padding-bottom: calc(1.2 * var(--mp-unit));
-  padding-left: calc(calc(1.6 * var(--mp-unit)) + env(safe-area-inset-left, 0px));
-  padding-right: calc(calc(1.6 * var(--mp-unit)) + env(safe-area-inset-right, 0px));
+  /* one line with an ellipsis until there is width to wrap, since a release filename would
+     otherwise run to four lines on a phone */
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 
   @media (min-width: 768px) {
+    padding: calc(2.4 * var(--mp-unit));
     padding-top: calc(calc(2.4 * var(--mp-unit)) + env(safe-area-inset-top, 0px));
-    padding-bottom: calc(2.4 * var(--mp-unit));
-    padding-left: calc(calc(2.4 * var(--mp-unit)) + env(safe-area-inset-left, 0px));
-    padding-right: calc(calc(2.4 * var(--mp-unit)) + env(safe-area-inset-right, 0px));
+    white-space: normal;
+    overflow: visible;
   }
 
   background: linear-gradient(180deg, rgba(0,0,0,0.4) 0%, rgba(0,0,0,0.3) 30%, rgba(0,0,0,0.2) 60%, rgba(0,0,0,0.1) 80%, transparent 100%);
-  /* visibility, not only opacity: a slot child 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 element visible for the length of the fade. */
-  transition: opacity 0.1s cubic-bezier(.4,0,1,1), visibility 0.1s;
-
-  .title {
-    ${fonts.headings.small}
-    color: white;
-    text-shadow: 0 0 4px rgba(0, 0, 0, 1);
-
-    /* one line with an ellipsis until there is width to wrap, since a release filename would
-       otherwise run to four lines on a phone */
-    flex: 1;
-    min-width: 0;
-    white-space: nowrap;
-    overflow: hidden;
-    text-overflow: ellipsis;
-
-    @media (min-width: 768px) {
-      white-space: normal;
-      overflow: visible;
-    }
-  }
-
-  /* pinned right with or without a title, so an app's readout does not jump sideways when a
-     filename arrives late */
-  .app-slot {
-    margin-left: auto;
-    flex: none;
-  }
+  transition: opacity 0.1s cubic-bezier(.4,0,1,1);
 `
 
 const spin = keyframes`
@@ -127,13 +88,7 @@ const errorMessage = (error: unknown) =>
     ? error.message
     : typeof error === 'string' ? error : 'Playback failed'
 
-export type OverlayProps = {
-  onCanvasRef: (element: HTMLCanvasElement | null) => void
-  /** The app's own content, drawn at the right of the top bar next to the title. */
-  overlay?: ReactNode
-}
-
-export const Overlay = ({ onCanvasRef, overlay }: OverlayProps) => {
+export const Overlay = ({ onCanvasRef }: { onCanvasRef: (element: HTMLCanvasElement | null) => void }) => {
   const title = usePlayer((state) => state.title)
   const hideUI = usePlayer((state) => state.hideUI)
   const playbackError = usePlayer((state) => state.playbackError)
@@ -144,14 +99,14 @@ export const Overlay = ({ onCanvasRef, overlay }: OverlayProps) => {
 
   return (
     <>
-      {title || overlay
+      {title
         ? (
           <div
-            css={topBarStyle}
-            style={{ ...hideUI ? { opacity: '0', visibility: 'hidden', pointerEvents: 'none' } : {} }}
+            className="title"
+            css={titleStyle}
+            style={{ ...hideUI ? { opacity: '0', pointerEvents: 'none' } : {} }}
           >
-            {title ? <div className="title">{title}</div> : undefined}
-            {overlay ? <div className="app-slot">{overlay}</div> : undefined}
+            {title}
           </div>
         )
         : undefined}

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

@@ -27,13 +27,26 @@ type CommonOptions = {
   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.
+   * The app's own content over the video: a download readout, a badge, a logo, anything the player
+   * itself has no opinion about.
    *
-   * 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.
+   * 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