@scarlett-player/ui 1.12.0 → 1.14.0

package/dist/index.js

@@ -269,6 +269,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;
@@ -339,6 +370,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;
@@ -1492,9 +1536,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;
@@ -1504,8 +1585,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;
@@ -1524,6 +1615,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) {
@@ -1538,7 +1630,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;
@@ -1561,6 +1655,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) {
@@ -1577,6 +1672,7 @@ var ProgressBar = class {
       }
     };
     this.onMouseMove = (e) => {
+      if (this.isExtensionInput(e)) return;
       this.updateTooltip(e.clientX);
     };
     this.onMouseLeave = () => {
@@ -1588,51 +1684,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" });
@@ -1651,6 +1712,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");
@@ -1668,6 +1731,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;
@@ -1727,6 +1874,7 @@ var ProgressBar = class {
       this.el.setAttribute("aria-valuenow", String(Math.floor(currentTime)));
       this.el.setAttribute("aria-valuetext", formatTime(currentTime));
     }
+    this.extension?.update();
   }
   /**
    * Label of the chapter containing a point on the timeline.
@@ -1835,6 +1983,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;
@@ -1849,6 +2048,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);
@@ -3403,7 +3606,7 @@ function resetControlRegistry() {
 }
 
 // src/version.ts
-var PKG_VERSION = true ? "1.12.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "1.13.0" : "0.0.0-dev";
 
 // src/index.ts
 var DEFAULT_LAYOUT = [
@@ -3744,10 +3947,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();
@@ -3929,7 +4135,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();
@@ -4099,13 +4315,16 @@ export {
   formatLiveTime,
   formatTime,
   getControlFactory,
+  hasTimelineExtension,
   icons,
   planFit,
   registerControl,
+  registerTimelineExtension,
   resetControlRegistry,
   resolveFitItems,
   styles,
   uiPlugin,
   unregisterControl,
-  unregisterControlsFor
+  unregisterControlsFor,
+  unregisterTimelineExtension
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scarlett-player/ui",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "UI Controls Plugin for Scarlett Player",
   "type": "module",
   "main": "dist/index.cjs",
@@ -29,7 +29,7 @@
     "typescript": "^5.3.0",
     "vitest": "^1.6.0",
     "jsdom": "^24.0.0",
-    "@scarlett-player/core": "1.12.0"
+    "@scarlett-player/core": "1.14.0"
   },
   "keywords": [
     "video",