@scarlett-player/ui 1.12.0 → 1.13.0

package/README.md

@@ -126,6 +126,40 @@ Any id a plugin registers through the control registry (`share`, `chapters`,
 `playlist-previous`, `playlist-next`, ...) can be placed in the same list. A
 control whose plugin is not loaded is skipped.
 
+## Timeline extensions
+
+The control registry lets a plugin contribute a *button*. `registerTimelineExtension` lets one contribute an editing layer over the **playback timeline** - the clip plugin's in/out handles are the first, and the reason it exists: an editor with its own miniature track cannot express a 30-second selection on a two-hour source, and makes the viewer pick points on a rail that is not the one they were just scrubbing.
+
+```typescript
+import { registerTimelineExtension } from '@scarlett-player/ui';
+
+const release = registerTimelineExtension(api.container, (surface) => {
+  surface.element.appendChild(myHandles);
+
+  return {
+    update: () => reposition(surface.getRailRect()),
+    onSeekStart: () => suspendMyPreview(),
+    onSeekEnd: () => {},
+    destroy: () => myHandles.remove(),
+  };
+});
+```
+
+`surface` gives an extension four things and nothing else:
+
+| Member | What it is |
+|---|---|
+| `element` | The layer to paint into: a sibling of the `role="slider"` seek element (never a child of it), positioned with exactly the rail's horizontal geometry and centred on it. `pointer-events: none`, so plain presses on the rail keep seeking; give your own hit targets `pointer-events: auto` |
+| `getRailRect()` | The rail's box, in client coordinates - the same box the slider maps a press against, so a `clientX`-to-time mapping agrees with the player's own seeking to the pixel |
+| `setEditing(active)` | Holds the control bar and progress bar visible and reserves the vertical room an editor needs around the rail. Independent of any control's `isMenuOpen()`, so an extension opened from a host's own button still holds the bar |
+| `setDragging(active)` | Suppresses ordinary seeking while the extension owns the pointer, and gets the hover tooltip out of the way |
+
+The extension gives back `update()` (called with the progress bar's own update, so it never has to observe the rail itself), `onSeekStart()` / `onSeekEnd()` for ordinary seeks it does **not** own - mouse, touch, keyboard and cancellation alike - and `destroy()`.
+
+There is one active extension per player, keyed by container. Registering again replaces and destroys the previous one; the returned disposer only ever removes the registration it made, so a late cleanup cannot unmount its successor. Registration works before or after the UI plugin initialises. `unregisterTimelineExtension(container)` drops a player's registration wholesale, and `hasTimelineExtension(container)` reports whether one is present.
+
+The UI package reads no plugin-specific state and gains no `IPluginAPI` surface for this: it offers a positioned layer and four lifecycle calls, and an extension paints into it.
+
 ## Keyboard Shortcuts
 
 | Key | Action |

package/dist/index.cjs

@@ -26,15 +26,18 @@ __export(index_exports, {
   formatLiveTime: () => import_core2.formatLiveTime,
   formatTime: () => import_core2.formatTime,
   getControlFactory: () => getControlFactory,
+  hasTimelineExtension: () => hasTimelineExtension,
   icons: () => icons,
   planFit: () => planFit,
   registerControl: () => registerControl,
+  registerTimelineExtension: () => registerTimelineExtension,
   resetControlRegistry: () => resetControlRegistry,
   resolveFitItems: () => resolveFitItems,
   styles: () => styles,
   uiPlugin: () => uiPlugin,
   unregisterControl: () => unregisterControl,
-  unregisterControlsFor: () => unregisterControlsFor
+  unregisterControlsFor: () => unregisterControlsFor,
+  unregisterTimelineExtension: () => unregisterTimelineExtension
 });
 module.exports = __toCommonJS(index_exports);
 var import_core4 = require("@scarlett-player/core");
@@ -302,6 +305,37 @@ var styles = `
   height: 5px;
 }
 
+/* ============================================
+   Timeline extension layer (timeline-registry.ts)
+
+   A zero-height line lying exactly on the rail's centre, spanning exactly the
+   rail's width, so an extension can position by percentage and land on the
+   same pixels the seek slider maps a press to. The 10px offset is the rail
+   centre in BOTH wrapper modes: the fine-pointer wrapper is 20px tall with the
+   3px rail centred (8.5..11.5 from the bottom), and the coarse-pointer wrapper
+   is 44px tall with 8.5px of bottom padding and align-items: flex-end, which
+   puts the rail in the same place.
+
+   Inert by default: only the explicit hit targets an extension puts inside it
+   take pointer input, so an ordinary press on the rail still seeks.
+   ============================================ */
+.sp-progress__extension {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 10px;
+  height: 0;
+  z-index: 3;
+  pointer-events: none;
+}
+
+/* Editing reserves a lane below the rail for an extension's second handle, by
+   lifting the whole wrapper clear of the control bar. The lane above needs no
+   reservation - it is over the picture. */
+.sp-progress-wrapper--editing {
+  bottom: calc(92px + var(--sp-inset-bottom, 0px));
+}
+
 .sp-progress__track {
   position: absolute;
   top: 0;
@@ -372,6 +406,19 @@ var styles = `
   transform: translate(-50%, -50%) scale(1);
 }
 
+/* While an extension owns the pointer the bar must not also look like it is
+   scrubbing: the tooltip is suppressed inline by the control, and the handle
+   stops responding to hover growth.
+
+   This has to come after the :hover and --dragging rules AND match their
+   specificity, which is why the hover case is spelled out rather than left to
+   the bare class: an extension drag is a pointer drag, so the pointer is over
+   the wrapper the whole time and the hover rule is always the competing one. */
+.sp-progress-wrapper--ext-dragging .sp-progress__handle,
+.sp-progress-wrapper--ext-dragging:hover .sp-progress__handle {
+  transform: translate(-50%, -50%);
+}
+
 /* Thumbnail Preview */
 .sp-thumbnail-preview {
   position: absolute;
@@ -1525,9 +1572,46 @@ var ThumbnailPreview = class {
   }
 };
 
+// src/timeline-registry.ts
+var registrations = /* @__PURE__ */ new WeakMap();
+var hosts = /* @__PURE__ */ new WeakMap();
+function registerTimelineExtension(owner, factory) {
+  const token = {};
+  registrations.set(owner, { factory, token });
+  hosts.get(owner)?.setFactory(factory);
+  return () => {
+    const current = registrations.get(owner);
+    if (!current || current.token !== token) return;
+    registrations.delete(owner);
+    hosts.get(owner)?.setFactory(null);
+  };
+}
+function unregisterTimelineExtension(owner) {
+  if (!registrations.has(owner)) return false;
+  registrations.delete(owner);
+  hosts.get(owner)?.setFactory(null);
+  return true;
+}
+function hasTimelineExtension(owner) {
+  return registrations.has(owner);
+}
+function attachTimelineHost(owner, host) {
+  hosts.set(owner, host);
+  const registration = registrations.get(owner);
+  if (registration) host.setFactory(registration.factory);
+  return () => {
+    if (hosts.get(owner) === host) hosts.delete(owner);
+  };
+}
+
 // src/controls/ProgressBar.ts
+var SEEK_KEYS = /* @__PURE__ */ new Set(["ArrowLeft", "ArrowRight", "Home", "End"]);
 var ProgressBar = class {
-  constructor(api) {
+  /**
+   * @param api - The per-player plugin API
+   * @param options - Optional hooks; see {@link ProgressBarOptions}
+   */
+  constructor(api, options = {}) {
     this.isDragging = false;
     this.lastSeekTime = 0;
     this.seekThrottleMs = 100;
@@ -1537,8 +1621,18 @@ var ProgressBar = class {
     this.renderedChapters = null;
     /** Duration the marker layer was last built against, since positions are a percentage of it. */
     this.renderedDuration = 0;
+    /** The mounted extension, or null when none is registered. */
+    this.extension = null;
+    /** Detaches this bar from the registry on destroy. */
+    this.detachTimelineHost = null;
+    /** True while the extension holds the pointer: ordinary seeking is suppressed. */
+    this.extensionDragging = false;
+    /** True while the extension is editing: the bar is held open and geometry reserved. */
+    this.extensionEditing = false;
     this.onMouseDown = (e) => {
+      if (this.isExtensionInput(e)) return;
       e.preventDefault();
+      this.extension?.onSeekStart();
       const video = getVideo(this.api.container);
       this.wasPlayingBeforeDrag = video ? !video.paused : false;
       this.isDragging = true;
@@ -1557,6 +1651,7 @@ var ProgressBar = class {
         this.seek(e.clientX, true);
         this.isDragging = false;
         this.el.classList.remove("sp-progress--dragging");
+        this.extension?.onSeekEnd();
         if (this.wasPlayingBeforeDrag) {
           const video = getVideo(this.api.container);
           if (video && video.paused) {
@@ -1571,7 +1666,9 @@ var ProgressBar = class {
       }
     };
     this.onTouchStart = (e) => {
+      if (this.isExtensionInput(e)) return;
       e.preventDefault();
+      this.extension?.onSeekStart();
       const video = getVideo(this.api.container);
       this.wasPlayingBeforeDrag = video ? !video.paused : false;
       this.isDragging = true;
@@ -1594,6 +1691,7 @@ var ProgressBar = class {
         }
         this.isDragging = false;
         this.el.classList.remove("sp-progress--dragging");
+        this.extension?.onSeekEnd();
         if (this.wasPlayingBeforeDrag) {
           const video = getVideo(this.api.container);
           if (video && video.paused) {
@@ -1610,6 +1708,7 @@ var ProgressBar = class {
       }
     };
     this.onMouseMove = (e) => {
+      if (this.isExtensionInput(e)) return;
       this.updateTooltip(e.clientX);
     };
     this.onMouseLeave = () => {
@@ -1621,51 +1720,16 @@ var ProgressBar = class {
     this.onKeyDown = (e) => {
       const video = getVideo(this.api.container);
       if (!video) return;
-      const step = 5;
-      const live = this.api.getState("live");
-      const seekableRange = this.api.getState("seekableRange");
-      if (live && seekableRange) {
-        switch (e.key) {
-          case "ArrowLeft":
-            e.preventDefault();
-            video.currentTime = Math.max(seekableRange.start, video.currentTime - step);
-            break;
-          case "ArrowRight":
-            e.preventDefault();
-            video.currentTime = Math.min(seekableRange.end, video.currentTime + step);
-            break;
-          case "Home":
-            e.preventDefault();
-            video.currentTime = seekableRange.start;
-            break;
-          case "End":
-            e.preventDefault();
-            video.currentTime = seekableRange.end;
-            break;
-        }
-      } else {
-        const duration = this.api.getState("duration") || 0;
-        switch (e.key) {
-          case "ArrowLeft":
-            e.preventDefault();
-            video.currentTime = Math.max(0, video.currentTime - step);
-            break;
-          case "ArrowRight":
-            e.preventDefault();
-            video.currentTime = Math.min(duration, video.currentTime + step);
-            break;
-          case "Home":
-            e.preventDefault();
-            video.currentTime = 0;
-            break;
-          case "End":
-            e.preventDefault();
-            video.currentTime = duration;
-            break;
-        }
+      if (!SEEK_KEYS.has(e.key)) return;
+      this.extension?.onSeekStart();
+      try {
+        this.applyKeyboardSeek(e, video);
+      } finally {
+        this.extension?.onSeekEnd();
       }
     };
     this.api = api;
+    this.options = options;
     this.wrapper = createElement("div", { className: "sp-progress-wrapper" });
     this.el = createElement("div", { className: "sp-progress" });
     const track = createElement("div", { className: "sp-progress__track" });
@@ -1684,6 +1748,8 @@ var ProgressBar = class {
     this.el.appendChild(this.thumbnailPreview.getElement());
     this.el.appendChild(this.tooltip);
     this.wrapper.appendChild(this.el);
+    this.extensionLayer = createElement("div", { className: "sp-progress__extension" });
+    this.wrapper.appendChild(this.extensionLayer);
     this.el.setAttribute("role", "slider");
     this.el.setAttribute("aria-label", "Seek");
     this.el.setAttribute("aria-valuemin", "0");
@@ -1701,6 +1767,90 @@ var ProgressBar = class {
     document.addEventListener("touchmove", this.onDocTouchMove, { passive: false });
     document.addEventListener("touchend", this.onTouchEnd);
     document.addEventListener("touchcancel", this.onTouchEnd);
+    this.detachTimelineHost = attachTimelineHost(this.api.container, {
+      setFactory: (factory) => this.mountExtension(factory)
+    });
+  }
+  // --------------------------------------------------------------------------
+  // Timeline extension seam
+  // --------------------------------------------------------------------------
+  /**
+   * Mount a registered extension factory, replacing any predecessor.
+   *
+   * The previous extension is destroyed and every lease it held is released
+   * first, so a replacement never inherits a stale editing or dragging state.
+   *
+   * @param factory - The factory to mount, or null to unmount
+   */
+  mountExtension(factory) {
+    if (this.extension) {
+      this.extension.destroy();
+      this.extension = null;
+      this.setExtensionDragging(false);
+      this.setExtensionEditing(false);
+      this.extensionLayer.replaceChildren();
+    }
+    if (!factory) return;
+    const surface = {
+      element: this.extensionLayer,
+      getRailRect: () => this.el.getBoundingClientRect(),
+      setEditing: (active) => this.setExtensionEditing(active),
+      setDragging: (active) => this.setExtensionDragging(active)
+    };
+    this.extension = factory(surface);
+    this.extension.update();
+  }
+  /** Whether a registered extension is currently editing. */
+  isTimelineEditing() {
+    return this.extensionEditing;
+  }
+  /**
+   * Apply the editing lease: reserve the handle lanes and hold the bar open.
+   *
+   * @param active - Whether the extension is editing
+   */
+  setExtensionEditing(active) {
+    if (this.extensionEditing === active) return;
+    this.extensionEditing = active;
+    this.wrapper.classList.toggle("sp-progress-wrapper--editing", active);
+    if (active) this.show();
+    this.options.onEditingChange?.(active);
+  }
+  /**
+   * Apply the pointer lease: suppress ordinary seeking while the extension
+   * owns the gesture, and get the hover tooltip out of the way.
+   *
+   * @param active - Whether the extension owns the pointer
+   */
+  setExtensionDragging(active) {
+    if (this.extensionDragging === active) return;
+    this.extensionDragging = active;
+    this.wrapper.classList.toggle("sp-progress-wrapper--ext-dragging", active);
+    if (active) {
+      this.isDragging = false;
+      this.el.classList.remove("sp-progress--dragging");
+      this.tooltip.style.opacity = "0";
+      this.thumbnailPreview.hide();
+    } else {
+      this.tooltip.style.opacity = "";
+    }
+  }
+  /**
+   * Whether an input event belongs to the extension rather than to seeking.
+   *
+   * Two independent reasons, and both are needed: the extension holds the
+   * pointer lease (its drag has moved off its handle and onto the rail), or
+   * the event started inside the extension layer at all. Touch and mouse
+   * compatibility events replay a handle press as a wrapper press, and only
+   * the target check catches those.
+   *
+   * @param event - The incoming pointer, mouse or touch event
+   * @returns True when the timeline must not act on it
+   */
+  isExtensionInput(event) {
+    if (this.extensionDragging) return true;
+    const target = event.target;
+    return target instanceof Node && this.extensionLayer.contains(target);
   }
   render() {
     return this.wrapper;
@@ -1760,6 +1910,7 @@ var ProgressBar = class {
       this.el.setAttribute("aria-valuenow", String(Math.floor(currentTime)));
       this.el.setAttribute("aria-valuetext", (0, import_core2.formatTime)(currentTime));
     }
+    this.extension?.update();
   }
   /**
    * Label of the chapter containing a point on the timeline.
@@ -1868,6 +2019,57 @@ var ProgressBar = class {
     this.filled.style.width = `${percent * 100}%`;
     this.handle.style.left = `${percent * 100}%`;
   }
+  /**
+   * Apply one keyboard seek to the element.
+   *
+   * @param e - The key event (already known to be a seek key)
+   * @param video - The player's media element
+   */
+  applyKeyboardSeek(e, video) {
+    const step = 5;
+    const live = this.api.getState("live");
+    const seekableRange = this.api.getState("seekableRange");
+    if (live && seekableRange) {
+      switch (e.key) {
+        case "ArrowLeft":
+          e.preventDefault();
+          video.currentTime = Math.max(seekableRange.start, video.currentTime - step);
+          break;
+        case "ArrowRight":
+          e.preventDefault();
+          video.currentTime = Math.min(seekableRange.end, video.currentTime + step);
+          break;
+        case "Home":
+          e.preventDefault();
+          video.currentTime = seekableRange.start;
+          break;
+        case "End":
+          e.preventDefault();
+          video.currentTime = seekableRange.end;
+          break;
+      }
+    } else {
+      const duration = this.api.getState("duration") || 0;
+      switch (e.key) {
+        case "ArrowLeft":
+          e.preventDefault();
+          video.currentTime = Math.max(0, video.currentTime - step);
+          break;
+        case "ArrowRight":
+          e.preventDefault();
+          video.currentTime = Math.min(duration, video.currentTime + step);
+          break;
+        case "Home":
+          e.preventDefault();
+          video.currentTime = 0;
+          break;
+        case "End":
+          e.preventDefault();
+          video.currentTime = duration;
+          break;
+      }
+    }
+  }
   seek(clientX, force = false) {
     const video = getVideo(this.api.container);
     if (!video) return;
@@ -1882,6 +2084,10 @@ var ProgressBar = class {
     }
   }
   destroy() {
+    this.detachTimelineHost?.();
+    this.detachTimelineHost = null;
+    this.extension?.destroy();
+    this.extension = null;
     this.wrapper.removeEventListener("mousedown", this.onMouseDown);
     this.wrapper.removeEventListener("mousemove", this.onMouseMove);
     this.wrapper.removeEventListener("mouseleave", this.onMouseLeave);
@@ -3777,10 +3983,13 @@ function uiPlugin(config = {}) {
       updateControls();
     });
   };
-  const hasOpenMenu = () => controls.some((control) => {
-    const menu = control;
-    return typeof menu.isMenuOpen === "function" && menu.isMenuOpen();
-  });
+  const hasOpenMenu = () => {
+    if (progressBar?.isTimelineEditing()) return true;
+    return controls.some((control) => {
+      const menu = control;
+      return typeof menu.isMenuOpen === "function" && menu.isMenuOpen();
+    });
+  };
   const showControls = () => {
     if (controlsVisible) {
       resetHideTimer();
@@ -3962,7 +4171,17 @@ function uiPlugin(config = {}) {
         bigPlayButton = new BigPlayButton(api, () => errorOverlay?.isVisible() ?? false);
         container.appendChild(bigPlayButton.render());
       }
-      progressBar = new ProgressBar(api);
+      progressBar = new ProgressBar(api, {
+        // A timeline editor is on screen for as long as the viewer needs it,
+        // which is longer than any hide delay. Holding visibility here rather
+        // than through a control's isMenuOpen() is deliberate: an extension
+        // can be opened from a host's own button, in a layout that lists no
+        // matching control at all.
+        onEditingChange: (active) => {
+          if (active) showControls();
+          else resetHideTimer();
+        }
+      });
       container.appendChild(progressBar.render());
       if (!isPlaying) {
         progressBar.show();
@@ -4132,13 +4351,16 @@ var index_default = uiPlugin;
   formatLiveTime,
   formatTime,
   getControlFactory,
+  hasTimelineExtension,
   icons,
   planFit,
   registerControl,
+  registerTimelineExtension,
   resetControlRegistry,
   resolveFitItems,
   styles,
   uiPlugin,
   unregisterControl,
-  unregisterControlsFor
+  unregisterControlsFor,
+  unregisterTimelineExtension
 });