@intellectif/lk-react 23.1.0 → 23.1.2

package/dist/ActivityMedia-vDiP-Psa.js

@@ -0,0 +1,636 @@
+'use client';
+import { i as useLkStrings } from "./LkIntlProvider-D_FdYXjQ.js";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { resolvePlaybackPolicy } from "@intellectif/lk-core";
+//#region src/components/shared/playback-group.ts
+/**
+* Media elements that must not play at the same time, keyed by group name.
+*
+* Module-level on purpose: the two players of a dictation are two separate
+* `<ActivityMedia>` mounts with no common ancestor that owns playback, and a
+* context would have to be threaded through every activity component to reach
+* them. A map keyed by a group name is the smaller mechanism, and it costs
+* nothing to the components that do not name a group. The caller mints the
+* name per mount — never from the activity id, which two renderings of one
+* item share, and never from `useId`, which two separately hydrated roots
+* share.
+*/
+const groups = /* @__PURE__ */ new Map();
+/** Adds an element to a group; returns the matching removal. */
+function joinPlaybackGroup(group, element) {
+	let members = groups.get(group);
+	if (members === void 0) {
+		members = /* @__PURE__ */ new Set();
+		groups.set(group, members);
+	}
+	members.add(element);
+	return () => {
+		const current = groups.get(group);
+		if (current === void 0) return;
+		current.delete(element);
+		if (current.size === 0) groups.delete(group);
+	};
+}
+/**
+* Pauses every OTHER member of the group. Called from a player's own `play`
+* event, so whichever recording the learner starts silences the rest.
+*
+* Pausing charges nothing: a budgeted play is charged inside the starting
+* player's own handler, and pausing another player neither refunds nor starts
+* anything — its transport records the position, so a later resume is a
+* resume and not a second play.
+*/
+function pausePlaybackGroupOthers(group, element) {
+	const members = groups.get(group);
+	if (members === void 0) return;
+	for (const member of members) if (member !== element && !member.paused) member.pause();
+}
+/**
+* Keeps `ref`'s element registered in `group` for as long as both exist.
+*
+* Re-registers after every commit rather than on a dependency list: the
+* element behind a ref can change while the ref object does not — a player
+* that swaps the SDK transport for the native bar when `renderMode` turns to
+* `review` mounts a new `<audio>` — and a list of `[ref, group]` would leave
+* the new element out of the group. Leaving and joining is a set delete and a
+* set add.
+*/
+function usePlaybackGroup(ref, group) {
+	useEffect(() => {
+		const element = ref.current;
+		if (group === void 0 || element === null) return;
+		return joinPlaybackGroup(group, element);
+	});
+}
+//#endregion
+//#region src/components/shared/AudioTransport.tsx
+/**
+* The SDK's own audio player, used whenever a policy has something to enforce.
+*
+* The browser's control bar cannot express a spent budget — its play button
+* stays enabled — and a control that looks operable and does nothing is a
+* WCAG 3.2.2 / 4.1.3 failure, so an enforcing policy replaces the bar rather
+* than lying with it. What replaces it is a SUPERSET minus what the policy
+* removes on purpose: play/pause, elapsed and total time, mute, volume, an
+* optional speed control, an optional scrubber, and a live plays-remaining
+* status. Volume and mute are never restricted by any policy — they affect no
+* assessment property, and a learner in a lab with a locked OS volume has no
+* other lever once the native bar is gone.
+*/
+/** A resume is a start within a quarter-second of where playback last stopped. */
+const RESUME_EPSILON = .25;
+/** Below this, a seek is the browser settling rather than the learner moving. */
+const SEEK_EPSILON = .35;
+/** A charged play that errors before this much audio played produced nothing. */
+const NO_PROGRESS = .25;
+const formatTime = (seconds) => {
+	if (!Number.isFinite(seconds) || seconds < 0) return "0:00";
+	const whole = Math.floor(seconds);
+	return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+};
+function AudioTransport({ media, policy, renderMode = "practice", disabled = false, locale, mediaBudget, mediaStrings, strings, onInteraction, playbackGroup }) {
+	const elementRef = useRef(null);
+	const statusId = useId();
+	usePlaybackGroup(elementRef, playbackGroup);
+	const suppliedStrings = mediaBudget?.strings ?? mediaStrings;
+	const s = {
+		...useLkStrings(strings).media,
+		...mediaStrings,
+		...mediaBudget?.strings
+	};
+	const budgeted = (mediaBudget?.enforced ?? renderMode !== "review") && policy.maxPlays !== null && mediaBudget !== void 0;
+	const maxPlays = policy.maxPlays ?? 0;
+	const usedRef = useRef(mediaBudget?.entry?.plays ?? 0);
+	const pendingRef = useRef(false);
+	const resumeAtRef = useRef(null);
+	const highWaterRef = useRef(0);
+	const chargeRef = useRef(null);
+	const seededRef = useRef(false);
+	const lastPositionRef = useRef(-1);
+	const selfStartRef = useRef(false);
+	const paidRef = useRef(false);
+	const [used, setUsed] = useState(usedRef.current);
+	const [playing, setPlaying] = useState(false);
+	const [pending, setPending] = useState(false);
+	const [elapsed, setElapsed] = useState(0);
+	const [duration, setDuration] = useState(0);
+	const [muted, setMuted] = useState(false);
+	const [volume, setVolume] = useState(1);
+	const [confirming, setConfirming] = useState(false);
+	const [notice, setNotice] = useState("");
+	const [noticeNonce, setNoticeNonce] = useState(0);
+	const remaining = Math.max(0, maxPlays - used);
+	const announce = useCallback((message) => {
+		setNotice(message);
+		setNoticeNonce((n) => n + 1);
+	}, []);
+	const emit = useCallback((type, playsUsed) => {
+		if (!budgeted || mediaBudget === void 0 || onInteraction === void 0) return;
+		onInteraction({
+			type,
+			activityId: mediaBudget.activityId ?? mediaBudget.slotId,
+			timestamp: Date.now(),
+			payload: {
+				mediaKey: mediaBudget.key,
+				mediaType: "audio",
+				playsUsed,
+				maxPlays,
+				playsRemaining: Math.max(0, maxPlays - playsUsed)
+			}
+		});
+	}, [
+		budgeted,
+		mediaBudget,
+		maxPlays,
+		onInteraction
+	]);
+	const reportPosition = useCallback((seconds) => {
+		mediaBudget?.onPosition?.(mediaBudget.key, seconds);
+	}, [mediaBudget]);
+	/** A start within a hair of where playback last stopped is a resume, not a play. */
+	const isResume = useCallback((element) => {
+		const at = resumeAtRef.current;
+		return at !== null && Math.abs(element.currentTime - at) < RESUME_EPSILON;
+	}, []);
+	const buildClaim = useCallback(() => {
+		if (mediaBudget === void 0) return null;
+		return {
+			key: mediaBudget.key,
+			previousPlaysUsed: usedRef.current,
+			playsUsed: usedRef.current + 1,
+			maxPlays,
+			playsRemaining: Math.max(0, maxPlays - (usedRef.current + 1)),
+			slotId: mediaBudget.slotId,
+			index: mediaBudget.index,
+			...mediaBudget.activityId !== void 0 ? { activityId: mediaBudget.activityId } : {}
+		};
+	}, [mediaBudget, maxPlays]);
+	const refuse = useCallback(() => {
+		announce(s.noPlaysRemaining);
+		emit("media-play-refused", usedRef.current);
+	}, [
+		announce,
+		emit,
+		s.noPlaysRemaining
+	]);
+	const startPlayback = useCallback(() => {
+		const element = elementRef.current;
+		if (element === null) return;
+		highWaterRef.current = element.currentTime;
+		selfStartRef.current = true;
+		element.play().catch(() => {
+			selfStartRef.current = false;
+		});
+	}, []);
+	const commit = useCallback((claim) => {
+		const element = elementRef.current;
+		chargeRef.current = {
+			claim,
+			at: element?.currentTime ?? 0
+		};
+		usedRef.current = claim.playsUsed;
+		setUsed(claim.playsUsed);
+		emit("media-play-consumed", claim.playsUsed);
+	}, [emit]);
+	/**
+	* Charges a play, then starts it.
+	*
+	* The confirmed tier holds playback until the consumer's atomic write
+	* settles, which is the only construction that catches a second tab: two
+	* mounts seeded at 0 both claim 1, and only the server can tell them apart.
+	*/
+	const claimAndStart = useCallback((element, alreadyPlaying) => {
+		if (disabled) {
+			if (alreadyPlaying) element.pause();
+			return;
+		}
+		const claim = buildClaim();
+		if (claim === null) return;
+		const result = mediaBudget?.onPlayConsumed?.(claim);
+		if (result !== void 0 && typeof result.then === "function") {
+			if (alreadyPlaying) element.pause();
+			pendingRef.current = true;
+			setPending(true);
+			result.then((grant) => {
+				const granted = grant !== void 0 && Number.isInteger(grant.playsUsed) ? grant.playsUsed : claim.playsUsed;
+				if (granted > maxPlays) {
+					usedRef.current = granted;
+					setUsed(granted);
+					refuse();
+					return;
+				}
+				commit({
+					...claim,
+					playsUsed: granted
+				});
+				startPlayback();
+			}).catch(() => {
+				announce(s.playFailed);
+				emit("media-play-errored", usedRef.current);
+			}).finally(() => {
+				pendingRef.current = false;
+				setPending(false);
+			});
+			return;
+		}
+		commit(claim);
+		if (alreadyPlaying) paidRef.current = true;
+		else startPlayback();
+	}, [
+		disabled,
+		buildClaim,
+		mediaBudget,
+		maxPlays,
+		commit,
+		startPlayback,
+		refuse,
+		announce,
+		emit,
+		s.playFailed
+	]);
+	const handleButton = useCallback(() => {
+		const element = elementRef.current;
+		if (element === null || pendingRef.current || disabled) return;
+		if (!element.paused) {
+			element.pause();
+			return;
+		}
+		if (!budgeted || isResume(element)) {
+			startPlayback();
+			return;
+		}
+		if (remaining === 0) {
+			refuse();
+			return;
+		}
+		if (remaining === 1 && !confirming) {
+			setConfirming(true);
+			return;
+		}
+		setConfirming(false);
+		claimAndStart(element, false);
+	}, [
+		disabled,
+		budgeted,
+		isResume,
+		startPlayback,
+		remaining,
+		refuse,
+		confirming,
+		claimAndStart
+	]);
+	const handleLoadedMetadata = useCallback(() => {
+		const element = elementRef.current;
+		if (element === null) return;
+		setDuration(Number.isFinite(element.duration) ? element.duration : 0);
+		const at = mediaBudget?.entry?.at;
+		if (!seededRef.current && typeof at === "number" && Number.isFinite(at) && at > 0) {
+			seededRef.current = true;
+			highWaterRef.current = at;
+			resumeAtRef.current = at;
+			element.currentTime = at;
+			setElapsed(at);
+		}
+	}, [mediaBudget]);
+	/**
+	* The budget lives on the ELEMENT's `play` event, not on the button, so a
+	* hardware media key, a browser extension or a scripted `el.play()` is
+	* charged too — and an exhausted budget stops playback inside the event,
+	* before a sample is audible.
+	*/
+	const handlePlay = useCallback(() => {
+		const element = elementRef.current;
+		if (element === null) return;
+		if (disabled) {
+			element.pause();
+			return;
+		}
+		if (playbackGroup !== void 0) pausePlaybackGroupOthers(playbackGroup, element);
+		if (selfStartRef.current) {
+			selfStartRef.current = false;
+			paidRef.current = true;
+			setPlaying(true);
+			return;
+		}
+		if (pendingRef.current) {
+			setPlaying(true);
+			return;
+		}
+		if (isResume(element)) {
+			paidRef.current = true;
+			setPlaying(true);
+			resumeAtRef.current = null;
+			return;
+		}
+		if (!budgeted) {
+			paidRef.current = true;
+			setPlaying(true);
+			return;
+		}
+		if (remaining === 0) {
+			element.pause();
+			refuse();
+			return;
+		}
+		setPlaying(true);
+		claimAndStart(element, true);
+	}, [
+		disabled,
+		playbackGroup,
+		isResume,
+		budgeted,
+		remaining,
+		refuse,
+		claimAndStart
+	]);
+	const handlePause = useCallback(() => {
+		const element = elementRef.current;
+		setPlaying(false);
+		if (element === null) return;
+		if (!paidRef.current) return;
+		paidRef.current = false;
+		resumeAtRef.current = element.currentTime;
+		reportPosition(element.currentTime);
+	}, [reportPosition]);
+	const handleEnded = useCallback(() => {
+		paidRef.current = false;
+		setPlaying(false);
+		resumeAtRef.current = null;
+		highWaterRef.current = 0;
+		chargeRef.current = null;
+		setElapsed(0);
+		reportPosition(0);
+	}, [reportPosition]);
+	const handleTimeUpdate = useCallback(() => {
+		const element = elementRef.current;
+		if (element === null) return;
+		setElapsed(element.currentTime);
+		highWaterRef.current = Math.max(highWaterRef.current, element.currentTime);
+		const whole = Math.floor(element.currentTime);
+		if (whole !== lastPositionRef.current) {
+			lastPositionRef.current = whole;
+			reportPosition(element.currentTime);
+		}
+	}, [reportPosition]);
+	const handleSeeking = useCallback(() => {
+		const element = elementRef.current;
+		if (element === null || policy.seek !== "none") return;
+		if (Math.abs(element.currentTime - highWaterRef.current) > SEEK_EPSILON) {
+			element.currentTime = highWaterRef.current;
+			announce(s.seekBlocked);
+		}
+	}, [
+		policy.seek,
+		announce,
+		s.seekBlocked
+	]);
+	const handleRateChange = useCallback(() => {
+		const element = elementRef.current;
+		if (element === null || policy.rate !== "fixed" || element.playbackRate === 1) return;
+		element.playbackRate = 1;
+		announce(s.rateBlocked);
+	}, [
+		policy.rate,
+		announce,
+		s.rateBlocked
+	]);
+	const handleError = useCallback(() => {
+		const charge = chargeRef.current;
+		const element = elementRef.current;
+		const progressed = charge !== null && element !== null && element.currentTime - charge.at >= NO_PROGRESS;
+		if (charge !== null && !progressed) {
+			if (mediaBudget?.onPlayRefunded !== void 0) {
+				usedRef.current = charge.claim.previousPlaysUsed;
+				setUsed(charge.claim.previousPlaysUsed);
+				mediaBudget.onPlayRefunded(charge.claim);
+				emit("media-play-refunded", charge.claim.previousPlaysUsed);
+			} else emit("media-play-errored", usedRef.current);
+		}
+		chargeRef.current = null;
+		setPlaying(false);
+		announce(s.playFailed);
+	}, [
+		mediaBudget,
+		emit,
+		announce,
+		s.playFailed
+	]);
+	useEffect(() => {
+		const element = elementRef.current;
+		if (element !== null) {
+			element.volume = volume;
+			element.muted = muted;
+		}
+	}, [volume, muted]);
+	const exhausted = budgeted && remaining === 0;
+	const buttonLabel = pending ? s.preparing : playing ? s.pause : s.play;
+	return /* @__PURE__ */ jsxs("figure", {
+		className: "lk-media",
+		"data-controls": "minimal",
+		children: [
+			/* @__PURE__ */ jsxs("audio", {
+				ref: elementRef,
+				className: "lk-media-el",
+				preload: "metadata",
+				"aria-label": media.alt || void 0,
+				onLoadedMetadata: handleLoadedMetadata,
+				onPlay: handlePlay,
+				onPause: handlePause,
+				onEnded: handleEnded,
+				onTimeUpdate: handleTimeUpdate,
+				onSeeking: handleSeeking,
+				onRateChange: handleRateChange,
+				onError: handleError,
+				children: [/* @__PURE__ */ jsx("source", { src: media.url }), media.captionsUrl ? /* @__PURE__ */ jsx("track", {
+					kind: "captions",
+					src: media.captionsUrl,
+					default: true
+				}) : null]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "lk-media-transport",
+				dir: "ltr",
+				...suppliedStrings !== void 0 && locale !== void 0 ? { lang: locale } : {},
+				children: [
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: "lk-media-play",
+						onClick: handleButton,
+						"aria-disabled": exhausted || disabled || void 0,
+						"aria-busy": pending || void 0,
+						"aria-label": exhausted ? `${s.play} — ${s.noPlaysRemaining}` : void 0,
+						"aria-describedby": budgeted ? statusId : void 0,
+						children: buttonLabel
+					}),
+					/* @__PURE__ */ jsxs("span", {
+						className: "lk-media-time",
+						children: [
+							formatTime(elapsed),
+							" / ",
+							formatTime(duration)
+						]
+					}),
+					policy.seek === "allow" ? /* @__PURE__ */ jsx("input", {
+						type: "range",
+						className: "lk-media-scrub",
+						min: 0,
+						max: duration || 0,
+						step: .1,
+						value: Math.min(elapsed, duration || 0),
+						"aria-label": s.seek,
+						"aria-valuetext": s.timeValue(formatTime(elapsed), formatTime(duration)),
+						onChange: (event) => {
+							const element = elementRef.current;
+							if (element !== null) element.currentTime = Number(event.target.value);
+						}
+					}) : null,
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: "lk-media-mute",
+						"aria-pressed": muted,
+						onClick: () => setMuted((m) => !m),
+						children: muted ? s.unmute : s.mute
+					}),
+					/* @__PURE__ */ jsx("input", {
+						type: "range",
+						className: "lk-media-volume",
+						min: 0,
+						max: 1,
+						step: .05,
+						value: volume,
+						"aria-label": s.volume,
+						onChange: (event) => setVolume(Number(event.target.value))
+					}),
+					policy.rate === "allow" ? /* @__PURE__ */ jsx("select", {
+						className: "lk-media-rate",
+						"aria-label": s.speed,
+						defaultValue: "1",
+						onChange: (event) => {
+							const element = elementRef.current;
+							if (element !== null) element.playbackRate = Number(event.target.value);
+						},
+						children: [
+							"0.75",
+							"1",
+							"1.25",
+							"1.5"
+						].map((rate) => /* @__PURE__ */ jsxs("option", {
+							value: rate,
+							children: [rate, "×"]
+						}, rate))
+					}) : null
+				]
+			}),
+			budgeted ? /* @__PURE__ */ jsx("p", {
+				className: "lk-media-plays",
+				id: statusId,
+				role: "status",
+				children: remaining > 0 ? s.playsRemaining(remaining, maxPlays) : s.noPlaysRemaining
+			}) : null,
+			/* @__PURE__ */ jsx("p", {
+				className: "lk-media-notice",
+				role: "alert",
+				children: notice
+			}, noticeNonce),
+			confirming ? /* @__PURE__ */ jsxs("fieldset", {
+				className: "lk-media-confirm",
+				children: [
+					/* @__PURE__ */ jsx("legend", { children: s.lastPlayConfirm }),
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: "lk-media-confirm-start",
+						autoFocus: true,
+						onClick: () => {
+							const element = elementRef.current;
+							setConfirming(false);
+							if (element !== null) claimAndStart(element, false);
+						},
+						children: s.lastPlayStart
+					}),
+					/* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: "lk-media-confirm-cancel",
+						onClick: () => setConfirming(false),
+						children: s.lastPlayCancel
+					})
+				]
+			}) : null
+		]
+	});
+}
+//#endregion
+//#region src/components/shared/ActivityMedia.tsx
+function ActivityMedia(props) {
+	const { media, renderMode = "practice", playbackGroup } = props;
+	const s = useLkStrings(props.strings);
+	const audioRef = useRef(null);
+	usePlaybackGroup(audioRef, media.type === "audio" ? playbackGroup : void 0);
+	if (media.type === "image") return /* @__PURE__ */ jsx("figure", {
+		className: "lk-media",
+		children: /* @__PURE__ */ jsx("img", {
+			className: "lk-media-el",
+			src: media.url,
+			alt: media.alt ?? ""
+		})
+	});
+	if (media.type === "audio") {
+		const policy = resolvePlaybackPolicy(media);
+		if (policy.maxPlays !== null && renderMode === "exam" && props.mediaBudget === void 0) throw new Error(`ActivityMedia: audio ${JSON.stringify(media.url)} declares maxPlays and is rendered in renderMode "exam" without a \`mediaBudget\` binding. Nothing would persist the count, so a refresh restores the full budget while the page says plays remain. Render it through <ActivitySequence mediaBudget={…}> or pass \`mediaBudget\` yourself.`);
+		if (policy.controls === "minimal" && renderMode !== "review") return /* @__PURE__ */ jsx(AudioTransport, {
+			...props,
+			media,
+			policy
+		});
+		const hints = renderMode === "review" ? [] : policy.nativeControlHints;
+		return /* @__PURE__ */ jsx("figure", {
+			className: "lk-media",
+			children: /* @__PURE__ */ jsxs("audio", {
+				ref: audioRef,
+				className: "lk-media-el",
+				controls: true,
+				"aria-label": media.alt || void 0,
+				...playbackGroup !== void 0 ? { onPlay: (event) => pausePlaybackGroupOthers(playbackGroup, event.currentTarget) } : {},
+				...hints.length > 0 ? { controlsList: hints.map((hint) => hint === "hide-download" ? "nodownload" : "noplaybackrate").join(" ") } : {},
+				children: [/* @__PURE__ */ jsx("source", { src: media.url }), media.captionsUrl ? /* @__PURE__ */ jsx("track", {
+					kind: "captions",
+					src: media.captionsUrl,
+					default: true
+				}) : null]
+			})
+		});
+	}
+	if (media.type === "embed") return /* @__PURE__ */ jsx("figure", {
+		className: "lk-media",
+		children: /* @__PURE__ */ jsx("div", {
+			className: "lk-media-embed",
+			children: /* @__PURE__ */ jsx("iframe", {
+				className: "lk-media-el",
+				src: media.url,
+				title: media.alt ?? s.embeddedMedia,
+				loading: "lazy",
+				referrerPolicy: "strict-origin-when-cross-origin",
+				sandbox: "allow-scripts allow-same-origin allow-presentation",
+				allow: "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share",
+				allowFullScreen: true
+			})
+		})
+	});
+	return /* @__PURE__ */ jsx("figure", {
+		className: "lk-media",
+		children: /* @__PURE__ */ jsxs("video", {
+			className: "lk-media-el",
+			controls: true,
+			"aria-label": media.alt || void 0,
+			children: [/* @__PURE__ */ jsx("source", { src: media.url }), media.captionsUrl ? /* @__PURE__ */ jsx("track", {
+				kind: "captions",
+				src: media.captionsUrl,
+				default: true
+			}) : null]
+		})
+	});
+}
+//#endregion
+export { ActivityMedia as t };
+
+//# sourceMappingURL=ActivityMedia-vDiP-Psa.js.map