+ );
+});
+
+function PlayerEpgTimelineComponent({
+ programs,
+ locale,
+ liveSessionAnchor,
+ onScrubbingChange,
+ onSeek,
+ seekStartTime,
+ supportsCatchup,
+}: PlayerEpgTimelineProps) {
+ const t = usePlayerTranslation(locale);
+ const clock = usePlaybackClock();
+ // Programme states only change on minute boundaries, so the list itself never needs the 1 Hz clock.
+ const nowMinuteMs = useWallClockMinute();
+
+ const rootRef = useRef(null);
+ const axisRef = useRef(null);
+ const trackRef = useRef(null);
+ const previewRef = useRef(null);
+ const previewBubbleRef = useRef(null);
+ const previewTimeRef = useRef(null);
+ const previewTitleRef = useRef(null);
+ const tooltipRef = useRef(null);
+ const popoverRef = useRef(null);
+ const frameRef = useRef(0);
+ const pointerXRef = useRef(null);
+ const dragRef = useRef(null);
+
+ const [anchorMs, setAnchorMs] = useState(() => snapToTick(Date.now(), TICK_MINUTES));
+ /** Non-null once the user pans: the window stops following playback until they return to it. */
+ const [manualAnchorMs, setManualAnchorMs] = useState(null);
+ const [scrubbing, setScrubbing] = useState(false);
+ const [hoveredProgramId, setHoveredProgramId] = useState(null);
+ const [tooltipVisible, setTooltipVisible] = useState(false);
+ const [action, setAction] = useState(null);
+
+ /** Where the window sits: the manual pan when the user has one, otherwise the followed anchor. */
+ const windowAnchorMs = manualAnchorMs ?? anchorMs;
+ const timelineWindow = useMemo(
+ () => createEpgTimelineWindow(windowAnchorMs, TICK_MINUTES, WINDOW_MINUTES_BEFORE, WINDOW_MINUTES_AFTER),
+ [windowAnchorMs],
+ );
+ const ticks = useMemo(() => createEpgTicks(timelineWindow, TICK_MINUTES), [timelineWindow]);
+ const blocks = useMemo(
+ () => createEpgTimelineBlocks(programs, timelineWindow, nowMinuteMs, supportsCatchup),
+ [programs, timelineWindow, nowMinuteMs, supportsCatchup],
+ );
+ const axisLabels = useMemo(() => createEpgAxisLabels(timelineWindow, ticks, blocks), [timelineWindow, ticks, blocks]);
+ const windowDayLabel = formatWindowDayLabel(timelineWindow.startMs, timelineWindow.endMs, nowMinuteMs, t);
+ const anchorBounds = useMemo(
+ () => getEpgAnchorBounds(programs, WINDOW_MINUTES_BEFORE, WINDOW_MINUTES_AFTER),
+ [programs],
+ );
+ const hoveredProgram = useMemo(
+ () => (hoveredProgramId ? (programs.find((program) => program.id === hoveredProgramId) ?? null) : null),
+ [hoveredProgramId, programs],
+ );
+
+ // Read by the (possibly stale) rAF callback and by pointer handlers, which only ever see the
+ // props of the render that created them.
+ const latestRef = useRef({ timelineWindow, programs, liveSessionAnchor, seekStartTime, t });
+ latestRef.current = { timelineWindow, programs, liveSessionAnchor, seekStartTime, t };
+
+ // Follow playback while the user has not panned. The anchor is snapped to a tick, so this
+ // commits state — and re-renders the band — once per tick rather than once per second.
+ useEffect(() => {
+ if (manualAnchorMs !== null) return;
+ const sync = () => {
+ const playbackMs = mseToWallClock(clock?.get() ?? 0, seekStartTime).getTime();
+ const next = snapToTick(Number.isFinite(playbackMs) ? playbackMs : Date.now(), TICK_MINUTES);
+ setAnchorMs((previous) => (previous === next ? previous : next));
+ };
+ sync();
+ return clock?.subscribe(sync);
+ }, [clock, seekStartTime, manualAnchorMs]);
+
+ // A seek re-centres the guide on where playback actually restarted.
+ // biome-ignore lint/correctness/useExhaustiveDependencies: the new start time is the trigger; the effect body itself only clears the manual pan.
+ useEffect(() => {
+ setManualAnchorMs(null);
+ }, [seekStartTime]);
+
+ const busy = scrubbing || action !== null;
+ useEffect(() => {
+ if (!busy) return;
+ onScrubbingChange(true);
+ return () => onScrubbingChange(false);
+ }, [busy, onScrubbingChange]);
+
+ const pan = useCallback(
+ (deltaMinutes: number) => {
+ // Pans from where the window is now, which is the followed anchor until the first pan.
+ setManualAnchorMs(clampToRange(windowAnchorMs + deltaMinutes * 60_000, anchorBounds));
+ },
+ [windowAnchorMs, anchorBounds],
+ );
+
+ const followPlayback = useCallback(() => {
+ setManualAnchorMs(null);
+ }, []);
+
+ // The wheel pans the ruler and must not reach the page or the player's own gestures.
+ useEffect(() => {
+ const root = rootRef.current;
+ if (!root) return;
+ const handleWheel = (event: WheelEvent) => {
+ if (event.deltaY === 0) return;
+ event.preventDefault();
+ event.stopPropagation();
+ pan(event.deltaY > 0 ? EPG_PAN_MINUTES : -EPG_PAN_MINUTES);
+ };
+ root.addEventListener("wheel", handleWheel, { passive: false });
+ return () => root.removeEventListener("wheel", handleWheel);
+ }, [pan]);
+
+ // Prompts and notices close on an outside press or Escape.
+ useEffect(() => {
+ if (!action) return;
+ const handlePointerDown = (event: PointerEvent) => {
+ if (popoverRef.current?.contains(event.target as Node)) return;
+ setAction(null);
+ };
+ const handleKeyDown = (event: KeyboardEvent) => {
+ if (event.key === "Escape") setAction(null);
+ };
+ document.addEventListener("pointerdown", handlePointerDown);
+ document.addEventListener("keydown", handleKeyDown);
+ return () => {
+ document.removeEventListener("pointerdown", handlePointerDown);
+ document.removeEventListener("keydown", handleKeyDown);
+ };
+ }, [action]);
+
+ // Plain information notices retire on their own; confirmations wait for an answer.
+ useEffect(() => {
+ if (action?.kind !== "notice") return;
+ const timer = window.setTimeout(() => setAction(null), NOTICE_DURATION_MS);
+ return () => window.clearTimeout(timer);
+ }, [action]);
+
+ // A window that moves under an open prompt would leave it pointing at the wrong programme.
+ // biome-ignore lint/correctness/useExhaustiveDependencies: the window's identity is the trigger
+ useEffect(() => {
+ setAction(null);
+ }, [timelineWindow.startMs]);
+
+ // Hover details: shown after a short dwell, hidden after a short grace period so crossing the
+ // gap between two blocks does not make the tooltip flicker.
+ useEffect(() => {
+ if (scrubbing || hoveredProgramId === null) {
+ const timer = window.setTimeout(() => setTooltipVisible(false), TOOLTIP_HIDE_DELAY_MS);
+ return () => window.clearTimeout(timer);
+ }
+ const timer = window.setTimeout(() => setTooltipVisible(true), TOOLTIP_SHOW_DELAY_MS);
+ return () => window.clearTimeout(timer);
+ }, [hoveredProgramId, scrubbing]);
+
+ /** Centres a floating element over the pointer, kept clear of the band's edges. */
+ const positionFloating = useCallback((element: HTMLElement | null) => {
+ const root = rootRef.current;
+ const pointerX = pointerXRef.current;
+ if (!element || !root || pointerX === null) return;
+ const rootRect = root.getBoundingClientRect();
+ const half = element.offsetWidth / 2;
+ const minX = half + TOOLTIP_EDGE_PADDING_PX;
+ const maxX = rootRect.width - half - TOOLTIP_EDGE_PADDING_PX;
+ const x = maxX < minX ? rootRect.width / 2 : Math.min(Math.max(pointerX - rootRect.left, minX), maxX);
+ element.style.left = `${x}px`;
+ }, []);
+
+ const positionTooltip = useCallback(() => {
+ positionFloating(tooltipRef.current);
+ }, [positionFloating]);
+
+ // Everything that follows the pointer is written straight to the DOM: a scrub must not
+ // re-render the band (and its programme blocks) at pointer frequency.
+ const paintPreview = useCallback(() => {
+ frameRef.current = 0;
+ const preview = previewRef.current;
+ const track = trackRef.current;
+ const pointerX = pointerXRef.current;
+ if (!preview || !track || pointerX === null) return;
+
+ const rect = track.getBoundingClientRect();
+ if (rect.width === 0) return;
+
+ const latest = latestRef.current;
+ const percent = clampPercent(((pointerX - rect.left) / rect.width) * 100);
+ const timeMs = percentToTime(latest.timelineWindow, percent);
+ const goesLive =
+ timeMs >= Date.now() || isNearLiveWallClock(new Date(timeMs), latest.liveSessionAnchor, latest.seekStartTime);
+
+ preview.style.left = `${percent}%`;
+ positionFloating(previewBubbleRef.current);
+ if (previewTimeRef.current) {
+ previewTimeRef.current.textContent = goesLive ? latest.t("goLive") : formatClockSeconds(timeMs);
+ }
+ if (previewTitleRef.current) {
+ previewTitleRef.current.textContent =
+ findEpgProgramAt(latest.programs, timeMs)?.title || latest.t("excellentProgram");
+ }
+ }, [positionFloating]);
+
+ const schedulePreview = useCallback(() => {
+ if (frameRef.current) return;
+ frameRef.current = window.requestAnimationFrame(paintPreview);
+ }, [paintPreview]);
+
+ useEffect(
+ () => () => {
+ if (frameRef.current) window.cancelAnimationFrame(frameRef.current);
+ },
+ [],
+ );
+
+ // The tooltip is centred on the pointer, so it is re-measured after every render: the band
+ // re-renders on the minute clock and on hover changes, and a stale centre would let a long
+ // title push past the edge of the video. The work is a single layout read.
+ useLayoutEffect(() => {
+ positionTooltip();
+ });
+
+ /**
+ * Marquee only for titles that actually overflow their block, measured in one read pass so a
+ * long guide costs a single layout, not one per block. The measured shift also drives the
+ * always-on scroll, so a name too long for its block stays readable without a pointer.
+ *
+ * Reads the DOM only, so it can also be replayed from the resize observer: the overflow of a
+ * name depends on how wide its block currently is.
+ */
+ const measureMarqueeTitles = useCallback(() => {
+ const track = trackRef.current;
+ if (!track) return;
+ const titles = Array.from(track.querySelectorAll("[data-epg-marquee]"));
+ const overflows = titles.map((title) => {
+ const clip = title.parentElement;
+ // The title is an inline-block sized to its text, so offsetWidth is the full label in any
+ // hover state; the clip is the room the block actually offers it.
+ return clip ? Math.max(0, title.offsetWidth - clip.clientWidth) : 0;
+ });
+ titles.forEach((title, index) => {
+ const overflow = overflows[index];
+ const block = title.closest(".player-epg-timeline__block");
+ if (overflow > 0) {
+ title.setAttribute("data-overflow", "true");
+ title.style.setProperty("--epg-marquee-shift", `-${overflow}px`);
+ // Marked on the block as well: the clip has to drop its ellipsis while the text scrolls,
+ // and a block-level hook avoids relying on :has() support.
+ block?.setAttribute("data-title-overflow", "true");
+ } else {
+ title.removeAttribute("data-overflow");
+ title.style.removeProperty("--epg-marquee-shift");
+ block?.removeAttribute("data-title-overflow");
+ }
+ });
+ }, []);
+
+ /**
+ * Axis labels are placed from their measured width: numbers are pinned to the ruler's edges
+ * instead of hanging off it, and a label that would collide with one already placed is dropped.
+ * Labels that fit stay in document order, so the ruler reads left to right.
+ *
+ * Reads the DOM only, so the resize observer can replay it — the placement is in pixels while
+ * the scale is in percentages, and a stale pass would leave the numbers off their own ticks.
+ */
+ const placeAxisLabels = useCallback(() => {
+ const axis = axisRef.current;
+ if (!axis) return;
+ const nodes = Array.from(axis.querySelectorAll("[data-epg-axis-label]"));
+ const axisWidth = axis.clientWidth;
+ if (axisWidth === 0) return;
+
+ // Writes first (clear the previous verdict), then reads, then writes again: one extra layout
+ // per window change buys exact widths instead of guessed ones.
+ for (const node of nodes) node.style.visibility = "";
+
+ const measured = nodes.map((node) => {
+ const width = node.offsetWidth;
+ const percent = Number(node.dataset.percent ?? "0");
+ return {
+ node,
+ width,
+ center: (percent / 100) * axisWidth,
+ // Whole hours name the scale, so they win the space when a boundary label would collide.
+ priority: node.dataset.kind === "hour" ? 0 : 1,
+ };
+ });
+ measured.sort((a, b) => a.priority - b.priority || a.center - b.center);
+
+ const placed: Array<{ left: number; right: number }> = [];
+ for (const { node, width, center } of measured) {
+ const half = width / 2;
+ // Pinned inside the ruler: a label never hangs off either end, whatever the window shows.
+ const pinnedCenter = Math.min(Math.max(center, half), Math.max(half, axisWidth - half));
+ const left = pinnedCenter - half;
+ const right = pinnedCenter + half;
+ const collides = placed.some(
+ (box) => left < box.right + AXIS_LABEL_GAP_PX && box.left - AXIS_LABEL_GAP_PX < right,
+ );
+ if (collides) {
+ node.style.visibility = "hidden";
+ continue;
+ }
+ placed.push({ left, right });
+ node.style.left = `${pinnedCenter}px`;
+ }
+ }, []);
+
+ // Both passes read the DOM and write only to absolutely positioned children, so they can be
+ // replayed whenever the band's box changes size — nothing they write can resize it again.
+ // biome-ignore lint/correctness/useExhaustiveDependencies: the rendered blocks and the language are the trigger; the body reads neither.
+ useLayoutEffect(() => {
+ measureMarqueeTitles();
+ }, [blocks, locale, measureMarqueeTitles]);
+
+ // biome-ignore lint/correctness/useExhaustiveDependencies: which labels are rendered is the trigger; the body reads neither.
+ useLayoutEffect(() => {
+ placeAxisLabels();
+ }, [axisLabels, placeAxisLabels]);
+
+ // The ruler's geometry is a percentage of the band, but its labels are pinned in pixels, so a
+ // pure resize — the sidebar opening or closing, fullscreen, picture-in-picture, a window drag,
+ // a rotated phone — has to replay both passes. The band does not even re-render for most of
+ // those: its props are unchanged, so nothing else would.
+ useEffect(() => {
+ const root = rootRef.current;
+ if (!root || typeof ResizeObserver === "undefined") return;
+ const observer = new ResizeObserver(() => {
+ placeAxisLabels();
+ measureMarqueeTitles();
+ });
+ observer.observe(root);
+ return () => observer.disconnect();
+ }, [placeAxisLabels, measureMarqueeTitles]);
+
+ // A late webfont changes how wide every label and title is without changing the band's box, so
+ // the resize observer would never hear about it. Re-measure once the fonts settle.
+ useEffect(() => {
+ let cancelled = false;
+ void document.fonts?.ready.then(() => {
+ if (cancelled) return;
+ placeAxisLabels();
+ measureMarqueeTitles();
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [placeAxisLabels, measureMarqueeTitles]);
+
+ const resolvePointerTime = useCallback((clientX: number): number | null => {
+ const track = trackRef.current;
+ if (!track) return null;
+ const rect = track.getBoundingClientRect();
+ if (rect.width === 0) return null;
+ return percentToTime(latestRef.current.timelineWindow, clampPercent(((clientX - rect.left) / rect.width) * 100));
+ }, []);
+
+ /** Never seek into the future: the last reachable moment is now, which reads as "go live". */
+ const seekTo = useCallback(
+ (timeMs: number) => {
+ onSeek(new Date(Math.min(timeMs, Date.now())));
+ },
+ [onSeek],
+ );
+
+ const showNotice = useCallback((message: string, anchorPercent: number) => {
+ setAction({ kind: "notice", message, anchorPercent });
+ }, []);
+
+ const handleTrackPointerDown = useCallback(
+ (event: ReactPointerEvent) => {
+ if (!event.isPrimary || dragRef.current) return;
+ if (event.pointerType === "mouse" && event.button !== 0) return;
+ const rect = trackRef.current?.getBoundingClientRect();
+ if (!rect || rect.width === 0) return;
+ // The band is the only place a horizontal drag may work: the surface gesture layer is a
+ // sibling underneath, so capturing here keeps zapping and swipe-seek out of the ruler.
+ event.preventDefault();
+ event.currentTarget.setPointerCapture(event.pointerId);
+ pointerXRef.current = event.clientX;
+ dragRef.current = { pointerId: event.pointerId, startX: event.clientX, moved: false };
+ setAction(null);
+ // A channel with no catch-up source has nothing to scrub to, but a click still deserves
+ // its answer, so the drag bookkeeping runs either way and only the preview is skipped.
+ if (supportsCatchup) {
+ setScrubbing(true);
+ schedulePreview();
+ }
+ },
+ [schedulePreview, supportsCatchup],
+ );
+
+ const handleTrackPointerMove = useCallback(
+ (event: ReactPointerEvent) => {
+ pointerXRef.current = event.clientX;
+ const drag = dragRef.current;
+ if (drag && drag.pointerId === event.pointerId) {
+ if (!drag.moved && Math.abs(event.clientX - drag.startX) > DRAG_THRESHOLD_PX) drag.moved = true;
+ if (supportsCatchup) {
+ event.preventDefault();
+ schedulePreview();
+ }
+ return;
+ }
+ if (tooltipVisible) positionTooltip();
+ },
+ [positionTooltip, schedulePreview, supportsCatchup, tooltipVisible],
+ );
+
+ const endDrag = useCallback((pointerId: number) => {
+ const drag = dragRef.current;
+ if (!drag || drag.pointerId !== pointerId) return null;
+ dragRef.current = null;
+ setScrubbing(false);
+ if (previewRef.current) previewRef.current.style.left = "";
+ return drag;
+ }, []);
+
+ const handleTrackPointerUp = useCallback(
+ (event: ReactPointerEvent) => {
+ const drag = endDrag(event.pointerId);
+ if (!drag) return;
+ event.preventDefault();
+ if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+ event.currentTarget.releasePointerCapture(event.pointerId);
+ }
+
+ const timeMs = resolvePointerTime(event.clientX);
+ if (timeMs === null) return;
+
+ if (drag.moved) {
+ if (supportsCatchup) seekTo(timeMs);
+ return;
+ }
+
+ // A press without travel is a click: the pure decision table turns the moment under the
+ // pointer into one of seek / go live / ask about catch-up / explain why nothing happens.
+ const anchorPercent = clampPercent(timeToPercent(timelineWindow, timeMs));
+ const tapAction = resolveEpgTapAction(programs, timeMs, Date.now(), supportsCatchup);
+ switch (tapAction.kind) {
+ case "seek":
+ seekTo(tapAction.timeMs);
+ return;
+ case "go-live":
+ onSeek(new Date());
+ return;
+ case "notice":
+ showNotice(
+ tapAction.reason === "not-aired" ? t("epgNotAiredYet") : t("epgCatchupUnsupported"),
+ anchorPercent,
+ );
+ return;
+ case "confirm-catchup":
+ setAction({ kind: "confirm-catchup", program: tapAction.program, anchorPercent });
+ }
+ },
+ [endDrag, onSeek, programs, resolvePointerTime, seekTo, showNotice, supportsCatchup, t, timelineWindow],
+ );
+
+ const handleTrackPointerCancel = useCallback(
+ (event: ReactPointerEvent) => {
+ if (!endDrag(event.pointerId)) return;
+ if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+ event.currentTarget.releasePointerCapture(event.pointerId);
+ }
+ },
+ [endDrag],
+ );
+
+ const handleTrackPointerOver = useCallback((event: ReactPointerEvent) => {
+ const block = (event.target as HTMLElement).closest("[data-epg-block-id]");
+ const id = block?.dataset.epgBlockId ?? null;
+ setHoveredProgramId((previous) => (previous === id ? previous : id));
+ }, []);
+
+ const handleTrackPointerLeave = useCallback(() => {
+ setHoveredProgramId(null);
+ }, []);
+
+ const confirmCatchup = useCallback(() => {
+ if (action?.kind !== "confirm-catchup") return;
+ setAction(null);
+ seekTo(action.program.start.getTime());
+ }, [action, seekTo]);
+
+ const dismissAction = useCallback(() => setAction(null), []);
+
+ return (
+
+
+ {/* Always on, including in the compact layout where the rest of the toolbar folds away:
+ without it, a window that crosses midnight has nothing naming the day. */}
+ {windowDayLabel}
+
+
+ {formatRange(timelineWindow.startMs, timelineWindow.endMs)}
+
+
+
+
+
+
+ {manualAnchorMs !== null && (
+
+ )}
+
+
+ {/* The scale is drawn by the ticks; the labels come from the hour ticks and the programme
+ boundaries, and are positioned from their measured width. */}
+
+
+ {/* The scrub preview and the prompts sit outside the track: the track clips its blocks,
+ and both must be able to float above the band. */}
+
+
+
+
+
+
+
+
+
+ {action && (
+
(null);
const tooltipRef = useRef(null);
const popoverRef = useRef(null);
+ const confirmButtonRef = useRef(null);
const frameRef = useRef(0);
const pointerXRef = useRef(null);
const dragRef = useRef(null);
@@ -281,7 +305,12 @@ function PlayerEpgTimelineComponent({
if (manualAnchorMs !== null) return;
const sync = () => {
const playbackMs = mseToWallClock(clock?.get() ?? 0, seekStartTime).getTime();
- const next = snapToTick(Number.isFinite(playbackMs) ? playbackMs : Date.now(), TICK_MINUTES);
+ if (!Number.isFinite(playbackMs)) return;
+ // Right after a seek or a channel change the media clock can still hold the previous
+ // stream's position, which would place the playhead hours into the future for a frame.
+ // A playhead ahead of the wall clock is never real, so that sample is ignored.
+ if (playbackMs > Date.now() + MAX_PLAUSIBLE_LEAD_MS) return;
+ const next = snapToTick(playbackMs, TICK_MINUTES);
setAnchorMs((previous) => (previous === next ? previous : next));
};
sync();
@@ -303,30 +332,85 @@ function PlayerEpgTimelineComponent({
const pan = useCallback(
(deltaMinutes: number) => {
- // Pans from where the window is now, which is the followed anchor until the first pan.
- setManualAnchorMs(clampToRange(windowAnchorMs + deltaMinutes * 60_000, anchorBounds));
+ // Functional update: one wheel event may spend several steps at once, and each has to build
+ // on the previous one instead of on the anchor this render captured. Pans from where the
+ // window is now, which is the followed anchor until the first pan.
+ setManualAnchorMs((previous) => clampEpgPan(previous ?? anchorMs, deltaMinutes * 60_000, anchorBounds));
},
- [windowAnchorMs, anchorBounds],
+ [anchorMs, anchorBounds],
);
const followPlayback = useCallback(() => {
setManualAnchorMs(null);
}, []);
- // The wheel pans the ruler and must not reach the page or the player's own gestures.
+ // The wheel pans the ruler and must not reach the page or the player's own gestures. A trackpad
+ // reports a flick as dozens of small deltas, so travel is accumulated and spent in whole steps;
+ // the accumulator is dropped when the direction turns or the gesture pauses.
useEffect(() => {
const root = rootRef.current;
if (!root) return;
+ let travelPx = 0;
+ let lastEventAt = 0;
+
const handleWheel = (event: WheelEvent) => {
- if (event.deltaY === 0) return;
+ const now = Date.now();
+ if (now - lastEventAt > WHEEL_GESTURE_GAP_MS) travelPx = 0;
+ lastEventAt = now;
+
+ const delta = normalizeWheelDelta(event.deltaX, event.deltaY, event.deltaMode);
+ if (delta === 0) return;
event.preventDefault();
event.stopPropagation();
- pan(event.deltaY > 0 ? EPG_PAN_MINUTES : -EPG_PAN_MINUTES);
+
+ if (travelPx !== 0 && Math.sign(delta) !== Math.sign(travelPx)) travelPx = 0;
+ travelPx += delta;
+ while (Math.abs(travelPx) >= EPG_WHEEL_STEP_PX) {
+ const step = Math.sign(travelPx);
+ travelPx -= step * EPG_WHEEL_STEP_PX;
+ pan(step * EPG_PAN_MINUTES);
+ }
};
+
root.addEventListener("wheel", handleWheel, { passive: false });
return () => root.removeEventListener("wheel", handleWheel);
}, [pan]);
+ // Keyboard panning for the focusable ruler. Registered natively so the player's global arrow
+ // shortcuts (±5 s seek, channel zap) do not also fire while the ruler has focus.
+ useEffect(() => {
+ const track = trackRef.current;
+ if (!track) return;
+ const handleKeyDown = (event: KeyboardEvent) => {
+ switch (event.key) {
+ case "ArrowLeft":
+ pan(-EPG_PAN_MINUTES);
+ break;
+ case "ArrowRight":
+ pan(EPG_PAN_MINUTES);
+ break;
+ case "Home":
+ followPlayback();
+ break;
+ default:
+ return;
+ }
+ event.preventDefault();
+ event.stopPropagation();
+ };
+ track.addEventListener("keydown", handleKeyDown);
+ return () => track.removeEventListener("keydown", handleKeyDown);
+ }, [pan, followPlayback]);
+
+ // A confirmation is a dialog: focus moves to its primary action, and back to the ruler when it
+ // closes, so keyboard users are never left without a focus target.
+ const confirmingCatchup = action?.kind === "confirm-catchup";
+ useEffect(() => {
+ if (!confirmingCatchup) return;
+ confirmButtonRef.current?.focus();
+ return () => trackRef.current?.focus();
+ }, [confirmingCatchup]);
+
// Prompts and notices close on an outside press or Escape.
useEffect(() => {
if (!action) return;
@@ -630,6 +714,33 @@ function PlayerEpgTimelineComponent({
return drag;
}, []);
+ /**
+ * The decision table, applied. Shared by the pointer tap and by an assistive-technology
+ * activation of a programme block, so both take the same path.
+ */
+ const runTapAction = useCallback(
+ (timeMs: number, anchorPercent: number) => {
+ const tapAction = resolveEpgTapAction(programs, timeMs, Date.now(), supportsCatchup);
+ switch (tapAction.kind) {
+ case "seek":
+ seekTo(tapAction.timeMs);
+ return;
+ case "go-live":
+ onSeek(new Date());
+ return;
+ case "notice":
+ showNotice(
+ tapAction.reason === "not-aired" ? t("epgNotAiredYet") : t("epgCatchupUnsupported"),
+ anchorPercent,
+ );
+ return;
+ case "confirm-catchup":
+ setAction({ kind: "confirm-catchup", program: tapAction.program, anchorPercent });
+ }
+ },
+ [onSeek, programs, seekTo, showNotice, supportsCatchup, t],
+ );
+
const handleTrackPointerUp = useCallback(
(event: ReactPointerEvent) => {
const drag = endDrag(event.pointerId);
@@ -649,26 +760,9 @@ function PlayerEpgTimelineComponent({
// A press without travel is a click: the pure decision table turns the moment under the
// pointer into one of seek / go live / ask about catch-up / explain why nothing happens.
- const anchorPercent = clampPercent(timeToPercent(timelineWindow, timeMs));
- const tapAction = resolveEpgTapAction(programs, timeMs, Date.now(), supportsCatchup);
- switch (tapAction.kind) {
- case "seek":
- seekTo(tapAction.timeMs);
- return;
- case "go-live":
- onSeek(new Date());
- return;
- case "notice":
- showNotice(
- tapAction.reason === "not-aired" ? t("epgNotAiredYet") : t("epgCatchupUnsupported"),
- anchorPercent,
- );
- return;
- case "confirm-catchup":
- setAction({ kind: "confirm-catchup", program: tapAction.program, anchorPercent });
- }
+ runTapAction(timeMs, clampPercent(timeToPercent(timelineWindow, timeMs)));
},
- [endDrag, onSeek, programs, resolvePointerTime, seekTo, showNotice, supportsCatchup, t, timelineWindow],
+ [endDrag, resolvePointerTime, runTapAction, seekTo, supportsCatchup, timelineWindow],
);
const handleTrackPointerCancel = useCallback(
@@ -766,8 +860,10 @@ function PlayerEpgTimelineComponent({
aria-label={t("epgTimelineLabel")}
aria-valuemin={0}
aria-valuemax={100}
- aria-valuenow={Math.round(clampPercent(timeToPercent(timelineWindow, nowMinuteMs)))}
- aria-valuetext={formatClockSeconds(nowMinuteMs)}
+ // Seeded from the followed anchor (the snapped playhead) and kept exact by EpgPlayhead,
+ // which owns the 1 Hz clock: the ruler reports where playback is, not the wall clock.
+ aria-valuenow={Math.round(clampPercent(timeToPercent(timelineWindow, windowAnchorMs)))}
+ aria-valuetext={formatClockSeconds(windowAnchorMs)}
className={clsx("player-epg-timeline__track touch-none select-none", supportsCatchup && "is-seekable")}
onPointerDown={handleTrackPointerDown}
onPointerMove={handleTrackPointerMove}
@@ -782,34 +878,51 @@ function PlayerEpgTimelineComponent({
style={{ ["--epg-hour-width" as string]: `${(60 / WINDOW_SPAN_MINUTES) * 100}%` }}
/>
- {blocks.map((block) => (
-
{/* The scrub preview and the prompts sit outside the track: the track clips its blocks,
@@ -827,14 +940,12 @@ function PlayerEpgTimelineComponent({
- {action && (
+ {action?.kind === "confirm-catchup" && (
)}
+ {/* role="status" is already a polite live region, and the notice retires on its own. */}
+ {action?.kind === "notice" && (
+
+
+
{action.message}
+
+ )}
+
*:not(.player-epg-timeline__date) {
+ /* The toolbar folds down to the controls a touch user cannot reach otherwise: the pan buttons
+ and "follow playback". Without them a compact layout could neither pan nor return to live. */
+ .player-epg-timeline__toolbar > :is(.player-epg-timeline__range, .player-epg-timeline__clock) {
display: none;
}
+ .player-epg-timeline__date {
+ font-size: 0.5625rem;
+ }
+
+ .player-epg-timeline__nav {
+ padding: 0;
+ }
+
+ .player-epg-timeline__follow {
+ font-size: 0.5625rem;
+ padding: 0.0625rem 0.25rem;
+ }
+
.player-epg-timeline__axis {
height: 1rem;
}
@@ -972,12 +1029,12 @@ html.dark.player-theme-simple .player-performance-channel-number-default {
/* ---------------------------- simple theme ---------------------------- */
html.player-theme-simple
- :is(
- .player-epg-timeline__track,
- .player-epg-timeline__tooltip,
- .player-epg-timeline__preview-bubble,
- .player-epg-timeline__popover
- ) {
+:is(
+ .player-epg-timeline__track,
+ .player-epg-timeline__tooltip,
+ .player-epg-timeline__preview-bubble,
+ .player-epg-timeline__popover
+) {
-webkit-backdrop-filter: none;
backdrop-filter: none;
box-shadow: none;
@@ -1003,6 +1060,43 @@ html.player-theme-simple .player-epg-timeline__block.is-live {
border-left-color: #93c5fd;
}
+html.player-theme-simple .player-epg-timeline__nowline {
+ background-image: none;
+ background-color: var(--epg-now);
+}
+
+/* biome-ignore lint/style/noDescendingSpecificity: as above — colour only, no shared property. */
+html.player-theme-simple .player-epg-timeline__playhead {
+ background-image: none;
+ background-color: var(--epg-accent);
+}
+
+/* biome-ignore lint/style/noDescendingSpecificity: as above — colour only, no shared property. */
+html.player-theme-simple .player-epg-timeline__preview {
+ background-image: none;
+ background-color: var(--epg-accent);
+}
+
+html.player-theme-simple .player-epg-timeline__playhead-grip {
+ background-color: var(--epg-accent-bright);
+}
+
+/* The simple theme flattens effects everywhere, so the glows go too — the lines and the grip
+ keep their colours, just without the halo. Declared after the flat colours above so the
+ specificity rises rather than falls with the cascade. */
+html.player-theme-simple
+:is(
+ .player-epg-timeline__block.is-live,
+ .player-epg-timeline__nowline,
+ .player-epg-timeline__playhead,
+ .player-epg-timeline__playhead-grip,
+ .player-epg-timeline__preview,
+ .player-epg-timeline__block-title
+) {
+ box-shadow: none;
+ filter: none;
+}
+
html.player-theme-simple .player-epg-timeline__tooltip,
html.player-theme-simple .player-epg-timeline__popover {
background-color: #0f172a;
diff --git a/web-ui/src/lib/epg-timeline.test.ts b/web-ui/src/lib/epg-timeline.test.ts
index 520ffea8..c239ad58 100644
--- a/web-ui/src/lib/epg-timeline.test.ts
+++ b/web-ui/src/lib/epg-timeline.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
import type { EPGProgram } from "../types/player";
import {
chooseEpgTickMinutes,
+ clampEpgPan,
clampPercent,
clampToRange,
createEpgAxisLabels,
@@ -15,6 +16,7 @@ import {
getLocalDayStart,
isTimeInWindow,
MINUTE_MS,
+ normalizeWheelDelta,
percentToTime,
resolveEpgTapAction,
snapToTick,
@@ -308,6 +310,56 @@ describe("getEpgAnchorBounds", () => {
});
});
+describe("clampEpgPan", () => {
+ const bounds = { minMs: 1000, maxMs: 2000 };
+
+ it("moves freely inside the bounds", () => {
+ expect(clampEpgPan(1500, 100, bounds)).toBe(1600);
+ expect(clampEpgPan(1500, -100, bounds)).toBe(1400);
+ });
+
+ it("stops at a bound instead of jumping across it", () => {
+ // Regression: clamping the target alone dragged the window backwards when the followed
+ // anchor already sat past the bound (playback near the end of the guide).
+ expect(clampEpgPan(2500, 100, bounds)).toBe(2500);
+ expect(clampEpgPan(500, -100, bounds)).toBe(500);
+ });
+
+ it("still clamps a move that starts inside and overshoots", () => {
+ expect(clampEpgPan(1950, 100, bounds)).toBe(2000);
+ expect(clampEpgPan(1050, -100, bounds)).toBe(1000);
+ });
+
+ it("pans without bounds when the guide is too short to bound it", () => {
+ expect(clampEpgPan(1500, 100, null)).toBe(1600);
+ });
+});
+
+describe("normalizeWheelDelta", () => {
+ it("passes pixels through", () => {
+ expect(normalizeWheelDelta(0, 40, 0)).toBe(40);
+ expect(normalizeWheelDelta(0, -40, 0)).toBe(-40);
+ });
+
+ it("scales lines and pages into pixels", () => {
+ expect(normalizeWheelDelta(0, 3, 1)).toBe(48);
+ expect(normalizeWheelDelta(0, 1, 2)).toBe(100);
+ });
+
+ it("accepts a horizontal swipe on a horizontal ruler", () => {
+ expect(normalizeWheelDelta(-30, 0, 0)).toBe(-30);
+ });
+
+ it("follows the axis the gesture pushed harder", () => {
+ expect(normalizeWheelDelta(5, -40, 0)).toBe(-40);
+ expect(normalizeWheelDelta(-40, 5, 0)).toBe(-40);
+ });
+
+ it("reports no travel for a pure tap or a zero delta", () => {
+ expect(normalizeWheelDelta(0, 0, 0)).toBe(0);
+ });
+});
+
describe("resolveEpgTapAction", () => {
const now = local(12).getTime();
const past = program(11, 0, 12, 0);
@@ -345,4 +397,19 @@ describe("resolveEpgTapAction", () => {
reason: "catchup-unsupported",
});
});
+
+ it("refuses a gap in the past when the source cannot replay", () => {
+ // Regression: a gap tap returned a seek even without catch-up, which the player then tried
+ // to serve as a catch-up URL.
+ const pastGapMs = local(11, 30).getTime();
+ expect(resolveEpgTapAction([live, future], pastGapMs, now, false)).toEqual({
+ kind: "notice",
+ reason: "catchup-unsupported",
+ });
+ });
+
+ it("still treats a gap at or after now as going live without catch-up", () => {
+ const futureGapMs = local(13, 30).getTime();
+ expect(resolveEpgTapAction([past], futureGapMs, now, false)).toEqual({ kind: "go-live" });
+ });
});
diff --git a/web-ui/src/lib/epg-timeline.ts b/web-ui/src/lib/epg-timeline.ts
index b6c90e15..e700905f 100644
--- a/web-ui/src/lib/epg-timeline.ts
+++ b/web-ui/src/lib/epg-timeline.ts
@@ -243,6 +243,10 @@ export function createEpgTimelineBlocks(
* The programme covering `timeMs`, matching `getCurrentProgram`'s "last started, not yet ended"
* rule but via binary search: the drag preview resolves this on every animation frame.
* `programs` must be sorted by start time.
+ *
+ * XMLTV allows rows to overlap, so the last row that *started* is not necessarily the one on air:
+ * the walk continues backwards to the last row that is still running, exactly like
+ * `getCurrentProgram`'s `findLast(start <= t && end > t)`.
*/
export function findEpgProgramAt(programs: readonly EPGProgram[], timeMs: number): EPGProgram | null {
let low = 0;
@@ -259,9 +263,12 @@ export function findEpgProgramAt(programs: readonly EPGProgram[], timeMs: number
}
}
- if (index < 0) return null;
- const program = programs[index];
- return program.end.getTime() > timeMs ? program : null;
+ for (let candidate = index; candidate >= 0; candidate--) {
+ const program = programs[candidate];
+ if (program.start.getTime() > timeMs) break;
+ if (program.end.getTime() > timeMs) return program;
+ }
+ return null;
}
/**
@@ -295,6 +302,44 @@ export function clampToRange(value: number, range: { minMs: number; maxMs: numbe
return Math.min(range.maxMs, Math.max(range.minMs, value));
}
+/**
+ * Where a pan should leave the anchor.
+ *
+ * The followed anchor is not clamped to the guide (playback can sit past the last programme), so
+ * clamping the *target* on its own would drag the window backwards when the user asks to move
+ * forwards near either end of the guide. Panning therefore only ever moves the window in the
+ * direction that was asked for, and simply stops at the boundary.
+ */
+export function clampEpgPan(
+ anchorMs: number,
+ deltaMs: number,
+ bounds: { minMs: number; maxMs: number } | null,
+): number {
+ const target = anchorMs + deltaMs;
+ if (!bounds) return target;
+ const bounded = clampToRange(target, bounds);
+ return deltaMs < 0 ? Math.min(anchorMs, bounded) : Math.max(anchorMs, bounded);
+}
+
+/**
+ * Mouse-wheel travel in pixels, with the two other delta modes normalised and both axes
+ * considered: a horizontal ruler responds to a horizontal swipe, and a trackpad's stream of
+ * small deltas is accumulated by the caller rather than applied event by event.
+ */
+export function normalizeWheelDelta(deltaX: number, deltaY: number, deltaMode: number): number {
+ // 0 = pixels, 1 = lines (~16 px), 2 = pages (~100 px)
+ const scale = deltaMode === 1 ? 16 : deltaMode === 2 ? 100 : 1;
+ const horizontal = deltaX * scale;
+ const vertical = deltaY * scale;
+ if (vertical === 0) return horizontal;
+ if (horizontal === 0) return vertical;
+ // A diagonal gesture belongs to the axis the user pushed harder.
+ return Math.abs(horizontal) > Math.abs(vertical) ? horizontal : vertical;
+}
+
+/** Wheel travel (px) that pans the window by one step. */
+export const EPG_WHEEL_STEP_PX = 48;
+
export type EpgTapAction =
/** Landed in a gap, or after a scrub: play from that moment. */
| { kind: "seek"; timeMs: number }
@@ -308,6 +353,10 @@ export type EpgTapAction =
/**
* What a click on the band should do, kept pure so the whole decision table is testable without
* a DOM. `timeMs` is the moment under the pointer, `nowMs` the current wall clock.
+ *
+ * A source without catch-up can only ever play the live edge, so every tap that would land in
+ * the past is answered with the reason instead of a seek the player cannot serve — including a
+ * tap in a gap between programmes, which has no row to classify.
*/
export function resolveEpgTapAction(
programs: readonly EPGProgram[],
@@ -316,7 +365,10 @@ export function resolveEpgTapAction(
supportsCatchup: boolean,
): EpgTapAction {
const program = findEpgProgramAt(programs, timeMs);
- if (!program) return { kind: "seek", timeMs };
+ if (!program) {
+ if (supportsCatchup) return { kind: "seek", timeMs };
+ return timeMs < nowMs ? { kind: "notice", reason: "catchup-unsupported" } : { kind: "go-live" };
+ }
const state = getEpgProgramState(program, nowMs);
if (state === "future") return { kind: "notice", reason: "not-aired" };