@sveltesentio/media 0.1.0 → 0.3.0

package/src/carousel.ts

@@ -0,0 +1,83 @@
+/**
+ * Headless carousel helpers shared by the `<Carousel>` shell and any consumer
+ * driving `embla-carousel-svelte` directly: a preset-aware embla options
+ * builder that bakes in the two obligations ADR-0012 leaves to the caller —
+ * reduced-motion (collapse transition duration to 0) and target-size
+ * (WCAG 2.5.8 nav-button sizing per interface preset). Pure and DOM-free.
+ *
+ * @see ADR-0012 (embla via shadcn) — the three consumer obligations.
+ */
+
+/** Interface-type preset governing nav-button target size (ADR-0047). */
+export type CarouselPreset = 'desktop' | 'handheld' | 'tv';
+
+/** Carousel scroll axis. */
+export type CarouselOrientation = 'horizontal' | 'vertical';
+
+/**
+ * The subset of `embla-carousel`'s options this helper sets. Structural so the
+ * package needs no `embla-carousel-svelte` dependency (it is an optional peer);
+ * the result spreads onto embla's own options object.
+ */
+export interface EmblaOptionsLike {
+	readonly loop: boolean;
+	readonly align: 'start' | 'center' | 'end';
+	readonly axis: 'x' | 'y';
+	readonly duration: number;
+	readonly dragFree: boolean;
+	/**
+	 * Per-media-query option overrides. The reduced-motion query collapses the
+	 * transition duration so SC 2.3.3 / 2.2.2 are honoured without JS.
+	 */
+	readonly breakpoints: Readonly<Record<string, { readonly duration: number }>>;
+}
+
+export interface CarouselOptionsInput {
+	/** Wrap from last slide to first. Default `false`. */
+	readonly loop?: boolean;
+	/** Slide alignment within the viewport. Default `'start'`. */
+	readonly align?: 'start' | 'center' | 'end';
+	/** Scroll axis. Default `'horizontal'`. */
+	readonly orientation?: CarouselOrientation;
+	/** Embla transition duration (embla time units). Default `25`. */
+	readonly duration?: number;
+	/** Allow free-scroll momentum dragging. Default `false`. */
+	readonly dragFree?: boolean;
+}
+
+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+
+/**
+ * Build embla options with the reduced-motion breakpoint always present, so a
+ * consumer who forgets obligation (a) from ADR-0012 still gets a
+ * reduced-motion-correct carousel. The breakpoint sets `duration: 0` (instant
+ * snap) under `prefers-reduced-motion: reduce`.
+ */
+export function buildCarouselOptions(input: CarouselOptionsInput = {}): EmblaOptionsLike {
+	return {
+		loop: input.loop ?? false,
+		align: input.align ?? 'start',
+		axis: (input.orientation ?? 'horizontal') === 'vertical' ? 'y' : 'x',
+		duration: input.duration ?? 25,
+		dragFree: input.dragFree ?? false,
+		breakpoints: {
+			[REDUCED_MOTION_QUERY]: { duration: 0 },
+		},
+	};
+}
+
+/**
+ * Minimum CSS px target size for the carousel's prev/next buttons per preset.
+ * `handheld` / `tv` upgrade to 44 px (WCAG 2.5.8 enhanced / touch + 10-foot
+ * reach); `desktop` keeps the shadcn `size="icon"` 32 px default — above the
+ * 24 px AA minimum (SC 2.5.8).
+ */
+export function navButtonTargetPx(preset: CarouselPreset): number {
+	return preset === 'desktop' ? 32 : 44;
+}
+
+/** Whether the user has requested reduced motion. SSR-safe (`false` server-side). */
+export function carouselPrefersReducedMotion(): boolean {
+	if (typeof globalThis.matchMedia !== 'function') return false;
+	return globalThis.matchMedia(REDUCED_MOTION_QUERY).matches;
+}

package/src/image.ts

@@ -0,0 +1,160 @@
+/**
+ * Pure responsive-image helpers: `srcset` / `sizes` string builders plus a
+ * width-descriptor candidate model. Framework-agnostic — no DOM, no Svelte —
+ * so the same logic drives a `<picture>`, an `<img srcset>`, or a server-side
+ * `Link: rel=preload` header.
+ */
+
+/** A `src`-templating function: maps a target pixel width to a URL. */
+export type SrcWidthTemplate = (width: number) => string;
+
+/** One `srcset` candidate: a URL paired with its intrinsic pixel width. */
+export interface SrcSetCandidate {
+	readonly url: string;
+	readonly width: number;
+}
+
+export interface SrcSetOptions {
+	/**
+	 * How to derive each candidate URL from a width. Either a template function
+	 * or a token-substitution string containing `{w}` (replaced with the width).
+	 * When omitted, `?w=<width>` is appended to `src` (or merged into an
+	 * existing query string).
+	 */
+	readonly template?: SrcWidthTemplate | string;
+}
+
+const WIDTH_TOKEN = /\{w\}/g;
+
+/** De-duplicate, drop non-positive/non-finite entries, and sort ascending. */
+function normaliseWidths(widths: readonly number[]): number[] {
+	const seen = new Set<number>();
+	for (const w of widths) {
+		if (Number.isFinite(w) && w > 0) seen.add(Math.round(w));
+	}
+	return [...seen].sort((a, b) => a - b);
+}
+
+/** Append/merge a `w` query param onto a URL without a URL parser dependency. */
+function appendWidthQuery(src: string, width: number): string {
+	const [base, hash = ''] = src.split('#', 2);
+	const safeBase = base ?? src;
+	const sep = safeBase.includes('?') ? '&' : '?';
+	const suffix = hash ? `#${hash}` : '';
+	return `${safeBase}${sep}w=${width}${suffix}`;
+}
+
+function resolveTemplate(
+	src: string,
+	template: SrcWidthTemplate | string | undefined,
+): SrcWidthTemplate {
+	if (typeof template === 'function') return template;
+	if (typeof template === 'string') {
+		return (width) => template.replace(WIDTH_TOKEN, String(width));
+	}
+	return (width) => appendWidthQuery(src, width);
+}
+
+/**
+ * Build the structured candidate list backing a `srcset`. Widths are
+ * normalised (de-duped, positive, integer, ascending) so callers can pass a
+ * raw breakpoint list in any order.
+ */
+export function buildSrcSetCandidates(
+	src: string,
+	widths: readonly number[],
+	options: SrcSetOptions = {},
+): SrcSetCandidate[] {
+	const resolved = resolveTemplate(src, options.template);
+	return normaliseWidths(widths).map((width) => ({
+		url: resolved(width),
+		width,
+	}));
+}
+
+/**
+ * Build a `srcset` attribute string with `w` width descriptors, e.g.
+ * `"/img?w=320 320w, /img?w=640 640w"`. Returns `""` for an empty width list.
+ */
+export function buildSrcSet(
+	src: string,
+	widths: readonly number[],
+	options: SrcSetOptions = {},
+): string {
+	return buildSrcSetCandidates(src, widths, options)
+		.map((c) => `${c.url} ${c.width}w`)
+		.join(', ');
+}
+
+/** One `sizes` media-condition / length pair. */
+export interface SizesRule {
+	/** A media condition, e.g. `"(min-width: 768px)"`. */
+	readonly condition: string;
+	/** A CSS length, e.g. `"50vw"` or `"600px"`. */
+	readonly size: string;
+}
+
+export interface BuildSizesOptions {
+	/**
+	 * The trailing default length applied when no condition matches. Defaults to
+	 * `"100vw"` — the responsive-image-correct fallback for a fluid layout.
+	 */
+	readonly fallback?: string;
+}
+
+/**
+ * Build a `sizes` attribute string from ordered conditional rules plus a
+ * fallback length, e.g. `"(min-width: 768px) 50vw, 100vw"`. Rules are emitted
+ * in array order — the browser uses the first matching condition.
+ */
+export function buildSizes(
+	rules: readonly SizesRule[],
+	options: BuildSizesOptions = {},
+): string {
+	const fallback = options.fallback ?? '100vw';
+	const conditional = rules.map((r) => `${r.condition} ${r.size}`);
+	return [...conditional, fallback].join(', ');
+}
+
+export interface ResponsiveImageAttrs {
+	readonly src: string;
+	readonly srcset: string;
+	readonly sizes: string;
+}
+
+export interface BuildResponsiveImageOptions extends SrcSetOptions {
+	readonly sizes?: readonly SizesRule[];
+	readonly sizesFallback?: string;
+	/**
+	 * Which width to use for the legacy `src` fallback attribute. Defaults to
+	 * the largest provided width so non-`srcset` browsers get full quality.
+	 */
+	readonly fallbackWidth?: number;
+}
+
+/**
+ * Compose `{ src, srcset, sizes }` ready to spread onto an `<img>`. The `src`
+ * fallback targets `fallbackWidth` (default: largest width) so legacy browsers
+ * without `srcset` support still receive a sensibly-sized asset.
+ */
+export function buildResponsiveImage(
+	src: string,
+	widths: readonly number[],
+	options: BuildResponsiveImageOptions = {},
+): ResponsiveImageAttrs {
+	const candidates = buildSrcSetCandidates(src, widths, options);
+	const fallbackWidth =
+		options.fallbackWidth ?? candidates.at(-1)?.width;
+	const resolved = resolveTemplate(src, options.template);
+	const fallbackSrc =
+		fallbackWidth === undefined ? src : resolved(fallbackWidth);
+	return {
+		src: fallbackSrc,
+		srcset: candidates.map((c) => `${c.url} ${c.width}w`).join(', '),
+		sizes: buildSizes(options.sizes ?? [], {
+			...(options.sizesFallback === undefined
+				? {}
+				: { fallback: options.sizesFallback }),
+		}),
+	};
+}

package/src/index.ts

@@ -1,2 +1,68 @@
-// @sveltesentio/media — not yet implemented (see .workingdir/PLAN.md)
-export {};
+export type {
+	HlsRendition,
+	PickRenditionOptions,
+	MediaSessionArtwork,
+	MediaSessionMetadataInit,
+	MediaSessionMetadata,
+	PlaybackStatus,
+	PlaybackEvent,
+	PlaybackState,
+	HlsLike,
+	HlsConstructorLike,
+	HlsAttachmentOptions,
+	HlsAttachment,
+} from './player.js';
+export {
+	pickRendition,
+	buildMediaSessionMetadata,
+	initialPlaybackState,
+	playbackReducer,
+	createHlsAttachment,
+} from './player.js';
+
+export type {
+	SrcWidthTemplate,
+	SrcSetCandidate,
+	SrcSetOptions,
+	SizesRule,
+	BuildSizesOptions,
+	ResponsiveImageAttrs,
+	BuildResponsiveImageOptions,
+} from './image.js';
+export {
+	buildSrcSet,
+	buildSrcSetCandidates,
+	buildSizes,
+	buildResponsiveImage,
+} from './image.js';
+
+export type { PlayerAction, MediaTrack } from './player-controls.js';
+export {
+	actionForKey,
+	assertCaptionsContract,
+	formatMediaTime,
+	clampVolume,
+} from './player-controls.js';
+
+export type {
+	CarouselPreset,
+	CarouselOrientation,
+	EmblaOptionsLike,
+	CarouselOptionsInput,
+} from './carousel.js';
+export {
+	buildCarouselOptions,
+	navButtonTargetPx,
+	carouselPrefersReducedMotion,
+} from './carousel.js';
+
+export type {
+	LqipPlaceholder,
+	ImageLoadingPriority,
+	ImageLoadingAttrs,
+} from './lqip.js';
+export {
+	buildPlaceholderStyle,
+	resolveAspectRatio,
+	imageLoadingAttrs,
+} from './lqip.js';

package/src/lqip.ts

@@ -0,0 +1,82 @@
+/**
+ * Headless LQIP (low-quality image placeholder) / blur-up helpers for the
+ * `<Image>` wrapper. Builds the inline background style for the blurred
+ * placeholder and resolves the layout-shift-free aspect ratio. Pure and
+ * DOM-free so the styling logic is unit-tested without rendering.
+ *
+ * @see docs/compose/image-optimization.md — LCP < 2.5 s / CLS < 0.1 gates.
+ */
+
+/** A placeholder source: an inline data-URI (or any URL) plus an optional solid colour. */
+export interface LqipPlaceholder {
+	/** Tiny blurred image, typically a base64 data-URI. */
+	readonly src?: string;
+	/** Solid fallback colour shown before the blurred image decodes. */
+	readonly color?: string;
+}
+
+/**
+ * Build the `background` CSS for the placeholder layer. A data-URI / URL becomes
+ * a covering `background-image` (with an optional solid colour beneath it);
+ * a colour-only placeholder becomes a flat fill. Returns `undefined` when no
+ * placeholder is supplied, so the caller can omit the layer entirely.
+ */
+export function buildPlaceholderStyle(placeholder: LqipPlaceholder | undefined): string | undefined {
+	if (placeholder === undefined) return undefined;
+	const { src, color } = placeholder;
+	if (src !== undefined && src !== '') {
+		const layers = [`url("${cssEscapeUrl(src)}") center / cover no-repeat`];
+		if (color !== undefined && color !== '') layers.push(color);
+		return `background: ${layers.join(', ')};`;
+	}
+	if (color !== undefined && color !== '') return `background: ${color};`;
+	return undefined;
+}
+
+/** Escape the characters that would break out of a CSS `url("…")` token. */
+function cssEscapeUrl(url: string): string {
+	return url.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Resolve an `aspect-ratio` CSS value from intrinsic width/height. Returns
+ * `undefined` when either dimension is missing or non-positive, so the caller
+ * only reserves space when it can do so correctly (avoids a wrong-ratio CLS).
+ */
+export function resolveAspectRatio(
+	width: number | undefined,
+	height: number | undefined,
+): string | undefined {
+	if (
+		width === undefined ||
+		height === undefined ||
+		!Number.isFinite(width) ||
+		!Number.isFinite(height) ||
+		width <= 0 ||
+		height <= 0
+	) {
+		return undefined;
+	}
+	return `${width} / ${height}`;
+}
+
+/** Loading priority for the underlying `<img>`. */
+export type ImageLoadingPriority = 'auto' | 'high';
+
+export interface ImageLoadingAttrs {
+	readonly loading: 'lazy' | 'eager';
+	readonly fetchpriority: 'high' | 'auto';
+	readonly decoding: 'async';
+}
+
+/**
+ * Derive the `loading` / `fetchpriority` / `decoding` attributes. `high`
+ * priority (an above-the-fold LCP hero) eager-loads with `fetchpriority="high"`;
+ * everything else lazy-loads. `decoding` is always `async` to keep the main
+ * thread free.
+ */
+export function imageLoadingAttrs(priority: ImageLoadingPriority = 'auto'): ImageLoadingAttrs {
+	return priority === 'high'
+		? { loading: 'eager', fetchpriority: 'high', decoding: 'async' }
+		: { loading: 'lazy', fetchpriority: 'auto', decoding: 'async' };
+}

package/src/player-controls.ts

@@ -0,0 +1,124 @@
+/**
+ * Headless player-control helpers for the `<Player>` shell: keyboard-event →
+ * action mapping (Vidstack-compatible defaults), a captions-invariant guard,
+ * and time formatting for the progress label. Pure and DOM-free so the mapping
+ * table is unit-tested without rendering a component.
+ *
+ * @see ADR-0042 (Vidstack `@next` + `hls.js`) — keyboard parity with Vidstack.
+ */
+
+import { ProblemError } from '@sveltesentio/core';
+
+/** A discrete player control intent produced by a key press. */
+export type PlayerAction =
+	| 'toggle-play'
+	| 'seek-back'
+	| 'seek-forward'
+	| 'volume-up'
+	| 'volume-down'
+	| 'toggle-mute'
+	| 'toggle-fullscreen'
+	| 'toggle-captions';
+
+/**
+ * Map a keyboard event to a player action, mirroring Vidstack's default
+ * shortcuts: Space / K toggle play, ← → seek, ↑ ↓ volume, M mute, F fullscreen,
+ * C captions. Returns `undefined` for unmapped keys or when a modifier is held
+ * (so browser/OS chords are never hijacked). Matching is case-insensitive.
+ */
+export function actionForKey(event: {
+	readonly key: string;
+	readonly ctrlKey?: boolean;
+	readonly metaKey?: boolean;
+	readonly altKey?: boolean;
+}): PlayerAction | undefined {
+	if (event.ctrlKey || event.metaKey || event.altKey) return undefined;
+	switch (event.key.toLowerCase()) {
+		case ' ':
+		case 'spacebar':
+		case 'k':
+			return 'toggle-play';
+		case 'arrowleft':
+			return 'seek-back';
+		case 'arrowright':
+			return 'seek-forward';
+		case 'arrowup':
+			return 'volume-up';
+		case 'arrowdown':
+			return 'volume-down';
+		case 'm':
+			return 'toggle-mute';
+		case 'f':
+			return 'toggle-fullscreen';
+		case 'c':
+			return 'toggle-captions';
+		default:
+			return undefined;
+	}
+}
+
+/** One caption / subtitle track for a consumer-supplied video. */
+export interface MediaTrack {
+	readonly src: string;
+	/** Track kind; `captions` / `subtitles` satisfy WCAG 1.2.2. */
+	readonly kind: 'captions' | 'subtitles' | 'descriptions' | 'chapters' | 'metadata';
+	/** BCP 47 language tag, e.g. `"en"`. */
+	readonly srclang?: string;
+	/** Human label shown in the track menu, e.g. `"English"`. */
+	readonly label?: string;
+	/** Whether the browser shows this track by default. */
+	readonly default?: boolean;
+}
+
+/**
+ * Enforce the captions invariant for video (WCAG 2.2 SC 1.2.2): a video
+ * `<Player>` must receive a `tracks` prop, even if empty. Passing `tracks`
+ * (including `[]`) is the explicit opt-out a consumer makes when the source has
+ * no spoken audio. Audio-only players are exempt. Throws an RFC 9457
+ * `ProblemError` rather than rendering a caption-less video.
+ */
+export function assertCaptionsContract(
+	viewType: 'video' | 'audio',
+	tracks: readonly MediaTrack[] | undefined,
+): void {
+	if (viewType === 'audio') return;
+	if (tracks === undefined) {
+		throw new ProblemError({
+			status: 500,
+			title: 'Captions contract violated',
+			detail:
+				'A video <Player> requires a `tracks` prop (use `tracks={[]}` to opt out explicitly when the source has no spoken audio). WCAG 2.2 SC 1.2.2.',
+			type: 'https://sveltesentio.dev/problems/media/captions-required',
+		});
+	}
+}
+
+/** Pad a non-negative integer to two digits. */
+function pad2(n: number): string {
+	return n < 10 ? `0${n}` : String(n);
+}
+
+/**
+ * Format a media time (seconds) as `M:SS` or `H:MM:SS`. Non-finite or negative
+ * input clamps to `0:00`. Used for the visible time-code and the progress
+ * slider's `aria-valuetext`.
+ */
+export function formatMediaTime(seconds: number): string {
+	const total = Number.isFinite(seconds) && seconds > 0 ? Math.floor(seconds) : 0;
+	const hrs = Math.floor(total / 3600);
+	const mins = Math.floor((total % 3600) / 60);
+	const secs = total % 60;
+	if (hrs > 0) return `${hrs}:${pad2(mins)}:${pad2(secs)}`;
+	return `${mins}:${pad2(secs)}`;
+}
+
+/**
+ * Clamp a volume to the valid `[0, 1]` range, mapping non-finite input to `0`.
+ * Volume key steps add/subtract `step` (default `0.1`) before clamping.
+ */
+export function clampVolume(value: number, step = 0): number {
+	const v = Number.isFinite(value) ? value + step : 0;
+	if (v < 0) return 0;
+	if (v > 1) return 1;
+	return v;
+}