@rixl/media-core 1.0.1 → 1.1.0

package/dist/lib/chapter-utils.js

@@ -1,147 +0,0 @@
-// src/lib/chapter-utils.ts
-/**
-* Check if a single chapter is within the video duration
-* @param chapter - The chapter to validate
-* @param videoDuration - The total video duration in seconds
-* @param tolerance - Tolerance in seconds for rounding errors (default: 1)
-* @returns Whether the chapter is within valid bounds
-*/
-function isChapterWithinDuration(chapter, videoDuration, tolerance = 1) {
-	return chapter.start_time_sec <= videoDuration + tolerance && chapter.end_time_sec <= videoDuration + tolerance;
-}
-/**
-* Validate chapters for use with chaptered progress bar
-* Returns false if:
-* - chapters is undefined or empty
-* - less than 2 chapters (need multiple for chaptered bar)
-* - any chapter exceeds video duration
-*
-* @param chapters - Array of chapters to validate
-* @param videoDuration - The total video duration in seconds
-* @param tolerance - Tolerance in seconds for rounding errors (default: 1)
-* @returns Whether chapters are valid for chaptered progress bar
-*/
-function validateChapters(chapters, videoDuration, tolerance = 1) {
-	if (!chapters || chapters.length <= 1) return false;
-	if (videoDuration <= 0) return false;
-	return chapters.every((chapter) => isChapterWithinDuration(chapter, videoDuration, tolerance));
-}
-/**
-* Calculate chapter end times based on next chapter start or video duration
-*/
-function calculateChaptersWithEnd(chapters, duration) {
-	return chapters.map((chapter, index) => {
-		const nextChapter = chapters[index + 1];
-		const endTime = nextChapter ? nextChapter.start_time_sec : duration;
-		return {
-			...chapter,
-			endTime,
-			durationSec: endTime - chapter.start_time_sec
-		};
-	});
-}
-function sliceHeatmapData({ heatmapData, chapterStartTime, chapterEndTime, videoDuration }) {
-	if (!heatmapData?.length || videoDuration <= 0) return [];
-	const startPercent = chapterStartTime / videoDuration;
-	const endPercent = chapterEndTime / videoDuration;
-	const startIndex = Math.floor(startPercent * heatmapData.length);
-	const endIndex = Math.ceil(endPercent * heatmapData.length);
-	return heatmapData.slice(startIndex, Math.max(startIndex + 1, endIndex));
-}
-/**
-* Calculate all heatmap slices for chapters
-*/
-function calculateHeatmapSlices(heatmapData, chapters, duration) {
-	if (!heatmapData?.length) return chapters.map(() => []);
-	return chapters.map((chapter) => sliceHeatmapData({
-		heatmapData,
-		chapterStartTime: chapter.start_time_sec,
-		chapterEndTime: chapter.endTime,
-		videoDuration: duration
-	}));
-}
-/**
-* Calculate global max value from heatmap data for consistent normalization
-*/
-function calculateGlobalMax(heatmapData) {
-	if (!heatmapData?.length) return 0;
-	return Math.max(...heatmapData);
-}
-/**
-* Calculate progress percentage within a chapter segment
-* @returns 0-100 percentage
-*/
-function calculateSegmentProgress(currentPosition, chapterStart, chapterEnd) {
-	if (currentPosition <= chapterStart) return 0;
-	if (currentPosition >= chapterEnd) return 100;
-	return (currentPosition - chapterStart) / (chapterEnd - chapterStart) * 100;
-}
-function calculateSegmentBufferRanges({ globalBufferRanges, chapterStart, chapterEnd, videoDuration }) {
-	if (chapterEnd - chapterStart <= 0 || videoDuration <= 0) return [];
-	const chapterStartPercent = chapterStart / videoDuration * 100;
-	const chapterEndPercent = chapterEnd / videoDuration * 100;
-	return globalBufferRanges.map((range) => {
-		if (range.end <= chapterStartPercent || range.start >= chapterEndPercent) return null;
-		const clampedStart = Math.max(range.start, chapterStartPercent);
-		const clampedEnd = Math.min(range.end, chapterEndPercent);
-		return {
-			start: (clampedStart - chapterStartPercent) / (chapterEndPercent - chapterStartPercent) * 100,
-			end: (clampedEnd - chapterStartPercent) / (chapterEndPercent - chapterStartPercent) * 100
-		};
-	}).filter((r) => r !== null);
-}
-/**
-* Calculate flex grow ratio for a chapter based on its duration
-*/
-function calculateFlexGrow(chapterDuration, videoDuration) {
-	if (videoDuration <= 0) return 0;
-	return chapterDuration / videoDuration;
-}
-function getCurrentPosition({ isDragging, progress, duration, currentTime }) {
-	return isDragging ? progress * duration : currentTime;
-}
-/**
-* Find which segment is hovered based on mouse X position
-* @param segments - Array of segment DOM elements
-* @param mouseX - Mouse X coordinate (clientX)
-* @returns Index of hovered segment, or null if none
-*/
-function findHoveredSegmentIndex(segments, mouseX) {
-	for (let i = 0; i < segments.length; i++) {
-		const segRef = segments[i];
-		if (!segRef) continue;
-		const segRect = segRef.getBoundingClientRect();
-		if (mouseX >= segRect.left && mouseX <= segRect.right) return i;
-	}
-	return null;
-}
-/**
-* Start time of the first chapter after the current position, or null when
-* already in the last chapter. Mirrors React useChapterNavigation.
-*/
-function getNextChapterStart(chapters, currentTime) {
-	if (!chapters?.length) return null;
-	const next = chapters.find((ch) => ch.start_time_sec > currentTime);
-	return next ? next.start_time_sec : null;
-}
-/** Seconds into a chapter after which Shift+P restarts it instead of jumping back. */
-const CHAPTER_RESTART_THRESHOLD_SECONDS = 3;
-/**
-* Target for "previous chapter": restart the current chapter when more than
-* 3s in (or when it is the first), otherwise jump to the previous chapter.
-* Mirrors React useChapterNavigation.
-*/
-function getPrevChapterTarget(chapters, currentTime) {
-	if (!chapters?.length) return null;
-	let currentChapterIndex = -1;
-	for (let i = chapters.length - 1; i >= 0; i--) if (chapters[i].start_time_sec <= currentTime) {
-		currentChapterIndex = i;
-		break;
-	}
-	if (currentChapterIndex < 0) return null;
-	const currentChapter = chapters[currentChapterIndex];
-	if (currentTime - currentChapter.start_time_sec > CHAPTER_RESTART_THRESHOLD_SECONDS || currentChapterIndex === 0) return currentChapter.start_time_sec;
-	return chapters[currentChapterIndex - 1].start_time_sec;
-}
-
-export { calculateChaptersWithEnd, calculateFlexGrow, calculateGlobalMax, calculateHeatmapSlices, calculateSegmentBufferRanges, calculateSegmentProgress, findHoveredSegmentIndex, getCurrentPosition, getNextChapterStart, getPrevChapterTarget, isChapterWithinDuration, sliceHeatmapData, validateChapters };

package/dist/lib/click-disambiguation.d.ts

@@ -1,44 +0,0 @@
-/**
- * Delay in milliseconds for single-click detection
- * Used to distinguish between single click (toggle play) and double click (fullscreen)
- */
-export declare const SINGLE_CLICK_DELAY_MS = 250;
-/**
- * Maximum time between clicks to be considered a double-click
- */
-export declare const DOUBLE_CLICK_THRESHOLD_MS = 400;
-export interface ClickDisambiguationState {
-  singleClickTimerId: ReturnType<typeof setTimeout> | null;
-  lastClickTime: number;
-}
-/**
- * Create initial click disambiguation state
- */
-export declare function createClickDisambiguationState(): ClickDisambiguationState;
-export interface HandleClickOptions {
-  state: ClickDisambiguationState;
-  hideUI: boolean;
-  allowFullscreen: boolean;
-  isExcludedTarget: boolean;
-  onTogglePlay: () => void;
-}
-/**
- * Handle a click event with disambiguation logic
- * Returns true if the click was handled, false if ignored
- */
-export declare function handleClick(options: HandleClickOptions): boolean;
-export interface HandleDoubleClickOptions {
-  state: ClickDisambiguationState;
-  allowFullscreen: boolean;
-  isExcludedTarget: boolean;
-  onToggleFullscreen: () => void;
-}
-/**
- * Handle a double-click event
- * Returns true if the double-click was handled, false if ignored
- */
-export declare function handleDoubleClick(options: HandleDoubleClickOptions): boolean;
-/**
- * Clean up click disambiguation state (clear any pending timers)
- */
-export declare function cleanupClickDisambiguation(state: ClickDisambiguationState): void;

package/dist/lib/click-disambiguation.js

@@ -1,80 +0,0 @@
-// src/lib/click-disambiguation.ts
-/**
-* Delay in milliseconds for single-click detection
-* Used to distinguish between single click (toggle play) and double click (fullscreen)
-*/
-const SINGLE_CLICK_DELAY_MS = 250;
-/**
-* Maximum time between clicks to be considered a double-click
-*/
-const DOUBLE_CLICK_THRESHOLD_MS = 400;
-/**
-* Create initial click disambiguation state
-*/
-function createClickDisambiguationState() {
-	return {
-		singleClickTimerId: null,
-		lastClickTime: 0
-	};
-}
-/**
-* Clear any pending single-click timer
-*/
-function clearPendingSingleClick(state) {
-	if (state.singleClickTimerId !== null) {
-		clearTimeout(state.singleClickTimerId);
-		state.singleClickTimerId = null;
-	}
-}
-/**
-* Schedule a single-click action after a delay
-* Allows time for a potential double-click to cancel it
-*/
-function scheduleSingleClick(state, onSingleClick) {
-	clearPendingSingleClick(state);
-	state.singleClickTimerId = setTimeout(() => {
-		onSingleClick();
-		state.singleClickTimerId = null;
-	}, 250);
-}
-/**
-* Handle a click event with disambiguation logic
-* Returns true if the click was handled, false if ignored
-*/
-function handleClick(options) {
-	const { state, hideUI, allowFullscreen, isExcludedTarget, onTogglePlay } = options;
-	if (hideUI || isExcludedTarget) return false;
-	const now = Date.now();
-	const timeSinceLastClick = now - state.lastClickTime;
-	state.lastClickTime = now;
-	if (timeSinceLastClick > 0 && timeSinceLastClick < 400) {
-		clearPendingSingleClick(state);
-		return true;
-	}
-	if (!allowFullscreen) {
-		onTogglePlay();
-		return true;
-	}
-	scheduleSingleClick(state, onTogglePlay);
-	return true;
-}
-/**
-* Handle a double-click event
-* Returns true if the double-click was handled, false if ignored
-*/
-function handleDoubleClick(options) {
-	const { state, allowFullscreen, isExcludedTarget, onToggleFullscreen } = options;
-	if (!allowFullscreen || isExcludedTarget) return false;
-	clearPendingSingleClick(state);
-	state.lastClickTime = 0;
-	onToggleFullscreen();
-	return true;
-}
-/**
-* Clean up click disambiguation state (clear any pending timers)
-*/
-function cleanupClickDisambiguation(state) {
-	clearPendingSingleClick(state);
-}
-
-export { DOUBLE_CLICK_THRESHOLD_MS, SINGLE_CLICK_DELAY_MS, cleanupClickDisambiguation, clearPendingSingleClick, createClickDisambiguationState, handleClick, handleDoubleClick, scheduleSingleClick };

package/dist/lib/click-outside.d.ts

@@ -1,68 +0,0 @@
-/**
- * Generic "click outside" detection with an optional exclusion attribute.
- *
- * Use case: a settings menu that should close when the user clicks outside it,
- * but NOT when the user clicks the button that opens it (otherwise the button
- * both opens and immediately closes the menu in the same pointer cycle).
- *
- * Pure, DOM-only, framework-agnostic. React/Lit/Vue wrappers call
- * `bindClickOutside` from their lifecycle hooks.
- */
-export interface ClickOutsideOptions {
-  /**
-   * Function that returns the "inside" element. Called on every pointer event,
-   * so the caller can pass a ref-like getter that may be null until the
-   * referenced element is mounted.
-   */
-  getContainer: () => HTMLElement | null;
-  /**
-   * Optional attribute name (e.g. `"data-settings-button"`). Any pointer event
-   * whose target is inside an element carrying this attribute is treated as
-   * "inside" and does NOT trigger `onOutsideClick`.
-   *
-   * This is what lets the button that toggles the menu coexist with a
-   * close-on-outside-click listener: the button's own clicks are ignored here,
-   * letting the button's own onClick decide whether to toggle.
-   */
-  excludeAttribute?: string;
-  /**
-   * Invoked when a pointer event lands outside both the container and (if
-   * configured) any element carrying `excludeAttribute`.
-   */
-  onOutsideClick: (event: MouseEvent) => void;
-}
-/**
- * Returns `true` when the given event target is inside an element carrying
- * the supplied attribute. When `attribute` is undefined, always returns false.
- */
-export declare function isInsideExcludedElement(target: EventTarget | null, attribute: string | undefined): boolean;
-/**
- * Returns `true` when the event lands outside both the container and any
- * excluded element.
- *
- * Checks the composed path as well as the plain target: document-level
- * listeners see shadow-DOM events retargeted to the host, and
- * `document.querySelector` cannot see into shadow roots — the composed path
- * is the only reliable record of where the click really landed.
- */
-export declare function isClickOutside(event: MouseEvent, container: HTMLElement | null, excludeAttribute: string | undefined): boolean;
-/**
- * Bind a `mousedown` listener on the document that invokes `onOutsideClick`
- * whenever the event lands outside the container and outside any element
- * carrying `excludeAttribute`.
- *
- * Returns a teardown function that removes the listener.
- *
- * The container is looked up via `getContainer()` on every event so the caller
- * can wire it to a ref that may be null at bind time.
- */
-export declare function bindClickOutside({ getContainer, excludeAttribute, onOutsideClick }: ClickOutsideOptions): () => void;
-/**
- * Bind a `visibilitychange` listener that fires `onHidden` when the document
- * is hidden. Returns a teardown function.
- *
- * Settings menus use this to close themselves when the user tabs away.
- * Lives next to `bindClickOutside` because the two are almost always wired
- * together for "dismissible overlay" behaviour.
- */
-export declare function bindDocumentHidden(onHidden: () => void): () => void;

package/dist/lib/click-outside.js

@@ -1,64 +0,0 @@
-// src/lib/click-outside.ts
-/**
-* Returns `true` when the given event target is inside an element carrying
-* the supplied attribute. When `attribute` is undefined, always returns false.
-*/
-function isInsideExcludedElement(target, attribute) {
-	if (!attribute) return false;
-	if (!(target instanceof Node)) return false;
-	const excluded = document.querySelector(`[${attribute}]`);
-	return Boolean(excluded?.contains(target));
-}
-/**
-* Returns `true` when the event lands outside both the container and any
-* excluded element.
-*
-* Checks the composed path as well as the plain target: document-level
-* listeners see shadow-DOM events retargeted to the host, and
-* `document.querySelector` cannot see into shadow roots — the composed path
-* is the only reliable record of where the click really landed.
-*/
-function isClickOutside(event, container, excludeAttribute) {
-	if (!container) return false;
-	const target = event.target;
-	if (!(target instanceof Node)) return false;
-	const path = event.composedPath();
-	if (path.includes(container) || container.contains(target)) return false;
-	if (excludeAttribute && path.some((node) => node instanceof Element && node.hasAttribute(excludeAttribute))) return false;
-	if (isInsideExcludedElement(target, excludeAttribute)) return false;
-	return true;
-}
-/**
-* Bind a `mousedown` listener on the document that invokes `onOutsideClick`
-* whenever the event lands outside the container and outside any element
-* carrying `excludeAttribute`.
-*
-* Returns a teardown function that removes the listener.
-*
-* The container is looked up via `getContainer()` on every event so the caller
-* can wire it to a ref that may be null at bind time.
-*/
-function bindClickOutside({ getContainer, excludeAttribute, onOutsideClick }) {
-	const handler = (event) => {
-		if (isClickOutside(event, getContainer(), excludeAttribute)) onOutsideClick(event);
-	};
-	document.addEventListener("mousedown", handler);
-	return () => document.removeEventListener("mousedown", handler);
-}
-/**
-* Bind a `visibilitychange` listener that fires `onHidden` when the document
-* is hidden. Returns a teardown function.
-*
-* Settings menus use this to close themselves when the user tabs away.
-* Lives next to `bindClickOutside` because the two are almost always wired
-* together for "dismissible overlay" behaviour.
-*/
-function bindDocumentHidden(onHidden) {
-	const handler = () => {
-		if (document.visibilityState === "hidden") onHidden();
-	};
-	document.addEventListener("visibilitychange", handler);
-	return () => document.removeEventListener("visibilitychange", handler);
-}
-
-export { bindClickOutside, bindDocumentHidden, isClickOutside, isInsideExcludedElement };

package/dist/lib/colors.d.ts

@@ -1,6 +0,0 @@
-export declare function hexToRGB(hex: string): {
-  r: number;
-  g: number;
-  b: number;
-};
-export declare function hexToRGBAString(hex: string, alpha?: number): string;

package/dist/lib/colors.js

@@ -1,16 +0,0 @@
-// src/lib/colors.ts
-function hexToRGB(hex) {
-	hex = hex.replace("#", "");
-	return {
-		r: parseInt(hex.substring(0, 2), 16),
-		g: parseInt(hex.substring(2, 4), 16),
-		b: parseInt(hex.substring(4, 6), 16)
-	};
-}
-function hexToRGBAString(hex, alpha = 100) {
-	const { r, g, b } = hexToRGB(hex);
-	alpha /= 100;
-	return `rgba(${r}, ${g}, ${b}, ${alpha})`;
-}
-
-export { hexToRGB, hexToRGBAString };

package/dist/lib/content-analytics.d.ts

@@ -1,27 +0,0 @@
-import { BuildEventParams } from "./analytics-utils.js";
-import { ContentType, Segment, ViewType } from "../types/analytics.js";
-export interface VideoAnalyticsPayload {
-  videoPositionMs?: number;
-  videoTotalDurationMs?: number;
-  segments?: Segment[];
-}
-export interface VideoSnapshot {
-  currentTime: number;
-  duration: number;
-}
-export interface BuildVideoAnalyticsPayloadParams {
-  contentType: ContentType;
-  viewType: ViewType;
-  video?: VideoSnapshot | null;
-  playerId?: string;
-}
-/**
- * Build and POST a single content-view event.
- */
-export declare function postContentEvent(params: BuildEventParams): void;
-/**
- * Compute the video position / duration / segments to attach to a
- * content-view event. Returns an empty payload for non-video content
- * or when the video snapshot is unavailable.
- */
-export declare function buildVideoAnalyticsPayload({ contentType, viewType, video, playerId }: BuildVideoAnalyticsPayloadParams): VideoAnalyticsPayload;

package/dist/lib/content-analytics.js

@@ -1,38 +0,0 @@
-import { buildContentViewEvent, secondsToMs, shouldIncludeSegments } from "./analytics-utils.js";
-import { postAnalytics } from "../api/analytics.js";
-import { analyticsStoreActions } from "../store/analytics-store.js";
-
-// src/lib/content-analytics.ts
-/**
-* Pure content-analytics helpers extracted from useContentAnalytics.
-*
-* - postContentEvent: build a content-view event and POST it.
-* - buildVideoAnalyticsPayload: derive the video position/duration/segments
-*   fields included in a content-view event. Reads currentTime/duration off
-*   a video-shaped snapshot; no React refs, no DOM dependencies beyond
-*   HTMLVideoElement properties.
-*/
-/**
-* Build and POST a single content-view event.
-*/
-function postContentEvent(params) {
-	postAnalytics([buildContentViewEvent(params)]);
-}
-/**
-* Compute the video position / duration / segments to attach to a
-* content-view event. Returns an empty payload for non-video content
-* or when the video snapshot is unavailable.
-*/
-function buildVideoAnalyticsPayload({ contentType, viewType, video, playerId }) {
-	if (contentType !== "video" || !video) return {};
-	const videoPositionMs = secondsToMs(video.currentTime);
-	const videoTotalDurationMs = secondsToMs(video.duration);
-	const segments = playerId && shouldIncludeSegments(viewType) ? analyticsStoreActions.getSegmentsWithCurrent(playerId, videoPositionMs) : void 0;
-	return {
-		videoPositionMs,
-		videoTotalDurationMs,
-		segments: segments && segments.length > 0 ? segments : void 0
-	};
-}
-
-export { buildVideoAnalyticsPayload, postContentEvent };

package/dist/lib/environment-effects.d.ts

@@ -1,89 +0,0 @@
-import { Viewport } from "./caption-utils.js";
-/**
- * Pure helpers for video-element environment effects.
- *
- * "Environment effects" = things the player has to keep in sync with the
- * surrounding document/window: fullscreen state, picture-in-picture state,
- * tab visibility, viewport size, and the volume/mute state derived from
- * player + user-interaction inputs.
- *
- * Everything in this module is framework-agnostic. React/Lit/Vue wrappers
- * supply the DOM listeners and the store-update callbacks; this module
- * supplies the predicates, the state derivations, and the listener factories.
- */
-/**
- * Bind the `document` `fullscreenchange` event to a callback that receives the
- * current fullscreen state.
- *
- * Returns a teardown function that removes the listener.
- */
-export declare function bindFullscreenChangeListener(onChange: (isFullscreen: boolean) => void): () => void;
-/**
- * Bind `enterpictureinpicture` and `leavepictureinpicture` events on a
- * video element to a callback that receives the current PiP state.
- *
- * Returns a teardown function.
- */
-export declare function bindPictureInPictureChangeListener(videoElement: HTMLVideoElement | null, onChange: (isPip: boolean) => void): () => void;
-export interface PipReentryOptions {
-  videoElement: HTMLVideoElement | null;
-  isCurrentlyInPip: boolean;
-}
-/**
- * Decide whether to re-request PiP when the document becomes hidden.
- *
- * Returns `true` when the caller should re-enter PiP on the supplied
- * video element. The actual `requestPictureInPicture()` call is left to the
- * caller (since it returns a promise and the caller chooses how to handle
- * errors).
- */
-export declare function shouldReenterPictureInPicture({ videoElement, isCurrentlyInPip }: PipReentryOptions): boolean;
-/**
- * Bind a `visibilitychange` handler that re-enters PiP whenever the document
- * becomes hidden and the player believes itself to be in PiP but the browser
- * has dropped out.
- *
- * Returns a teardown function.
- */
-export declare function bindPipVisibilityReentry(getOptions: () => PipReentryOptions, onError?: (error: unknown) => void): () => void;
-export interface AppliedVolumeSync {
-  /** The `muted` value that should be assigned to the video element. */
-  muted: boolean;
-  /** The `volume` value that should be assigned, or `null` if not changing. */
-  volume: number | null;
-  /** When non-null, the store's current `volume` should be updated to this value. */
-  storeVolumeUpdate: number | null;
-}
-export interface DeriveVolumeSyncOptions {
-  /** Hard mute applied by the consumer (e.g. theme override). */
-  forcedMuted: boolean;
-  /** The player's persisted `muted` state. */
-  playerMuted: boolean;
-  /** Whether the user has interacted with the player yet. */
-  playerInteracted: boolean;
-  /** The player's persisted `volume`. */
-  playerVolume: number;
-  /** The player's persisted `previousVolume` (used to restore on unmute). */
-  playerPreviousVolume: number;
-}
-/**
- * Pure derivation of the values that should be written to the video element
- * (and back to the store) given the current player state.
- *
- * Mirrors the behaviour previously implemented inside `useVolumeEffect`:
- *
- * 1. When the caller forces mute, nothing else is touched.
- * 2. Otherwise, `shouldBeMuted` decides the effective mute state.
- * 3. When unmuted, `getRestoredVolume` resolves the volume to assign, and the
- *    store is updated only when the current persisted volume is `0`.
- */
-export declare function deriveVolumeSync({ forcedMuted, playerMuted, playerInteracted, playerVolume, playerPreviousVolume }: DeriveVolumeSyncOptions): AppliedVolumeSync | null;
-/**
- * Observe a container element's viewport size, invoking the callback with the
- * current `{width, height}` whenever it changes (via `ResizeObserver`) or
- * the window resizes.
- *
- * Returns a teardown function.
- */
-export declare function observeViewport(container: HTMLElement | null, onChange: (viewport: Viewport) => void): () => void;
-export type { Viewport };