@loidolt/theme-svelte 0.4.0 → 0.6.0

package/dist/internal/media/MediaStage.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { MediaZoom } from '../../media-zoom.svelte.js';
+import type { MediaItem } from '../../media-utils.js';
+interface Props {
+    item: MediaItem;
+    zoom?: MediaZoom;
+    /** Images fill the frame (`cover`) in a carousel, and fit whole (`contain`) in a lightbox. */
+    fit?: 'contain' | 'cover';
+}
+declare const MediaStage: import("svelte").Component<Props, {}, "">;
+type MediaStage = ReturnType<typeof MediaStage>;
+export default MediaStage;

package/dist/internal/media/MediaTile.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+  import Thumbnail from '../../components/Thumbnail.svelte';
+  import { mediaLabel, mediaThumbnail, type MediaItem } from '../../media-utils.js';
+
+  /* One pressable tile in a MediaGrid: the preview, plus a kind marker for time-based media. */
+  interface Props {
+    item: MediaItem;
+    index: number;
+    ratio?: string | number;
+    kindLabels: Record<MediaItem['kind'], string>;
+    onSelect: () => void;
+  }
+
+  let { item, index, ratio, kindLabels, onSelect }: Props = $props();
+
+  const label = $derived(mediaLabel(item, index));
+  const preview = $derived(mediaThumbnail(item));
+</script>
+
+<button
+  type="button"
+  class="ldt-media-tile"
+  data-roving-item
+  aria-label={item.kind === 'image' ? label : `${label}, ${kindLabels[item.kind]}`}
+  onclick={onSelect}
+>
+  <Thumbnail src={preview} alt="" {ratio} fit="cover">
+    {#snippet overlay()}
+      {#if item.kind !== 'image'}<span class="ldt-media-tile__kind" aria-hidden="true"
+          >{kindLabels[item.kind]}</span
+        >{/if}
+    {/snippet}
+  </Thumbnail>
+  {#if item.caption}<span class="ldt-media-tile__caption" aria-hidden="true">{item.caption}</span
+    >{/if}
+</button>

package/dist/internal/media/MediaTile.svelte.d.ts

@@ -0,0 +1,11 @@
+import { type MediaItem } from '../../media-utils.js';
+interface Props {
+    item: MediaItem;
+    index: number;
+    ratio?: string | number;
+    kindLabels: Record<MediaItem['kind'], string>;
+    onSelect: () => void;
+}
+declare const MediaTile: import("svelte").Component<Props, {}, "">;
+type MediaTile = ReturnType<typeof MediaTile>;
+export default MediaTile;

package/dist/internal/media/keys.d.ts

@@ -0,0 +1,7 @@
+import type { MediaPlayer } from '../../media-player.svelte.js';
+/**
+ * The shortcuts every web player shares: Space or K plays, arrows seek and change volume, M
+ * mutes, F goes full screen, C toggles captions. Keys meant for a focused control — typing in a
+ * field, stepping a range, pressing a button — are left alone.
+ */
+export declare function mediaKeydown(player: MediaPlayer, container: () => HTMLElement | null): (event: KeyboardEvent) => void;

package/dist/internal/media/keys.js

@@ -0,0 +1,51 @@
+/**
+ * The shortcuts every web player shares: Space or K plays, arrows seek and change volume, M
+ * mutes, F goes full screen, C toggles captions. Keys meant for a focused control — typing in a
+ * field, stepping a range, pressing a button — are left alone.
+ */
+export function mediaKeydown(player, container) {
+    return (event) => {
+        const target = event.target;
+        if (event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        if (target.matches('input, select, textarea'))
+            return;
+        if (target.matches('button') && (event.key === ' ' || event.key === 'Enter'))
+            return;
+        const handled = (() => {
+            switch (event.key) {
+                case ' ':
+                case 'k':
+                    void player.toggle();
+                    return true;
+                case 'ArrowLeft':
+                    player.seekBy(-5);
+                    return true;
+                case 'ArrowRight':
+                    player.seekBy(5);
+                    return true;
+                case 'ArrowUp':
+                    player.setVolume(player.volume + 0.1);
+                    return true;
+                case 'ArrowDown':
+                    player.setVolume(player.volume - 0.1);
+                    return true;
+                case 'm':
+                    player.toggleMute();
+                    return true;
+                case 'f':
+                    void player.toggleFullscreen(container());
+                    return true;
+                case 'c':
+                    if (!player.tracks.length)
+                        return false;
+                    player.selectTrack(player.activeTrack === null ? 0 : null);
+                    return true;
+                default:
+                    return false;
+            }
+        })();
+        if (handled)
+            event.preventDefault();
+    };
+}

package/dist/internal/media/labels.d.ts

@@ -0,0 +1,19 @@
+/** Every string the media players show or announce. */
+export interface MediaPlayerLabels {
+    play: string;
+    pause: string;
+    mute: string;
+    unmute: string;
+    seek: string;
+    volume: string;
+    speed: string;
+    captions: string;
+    pictureInPicture: string;
+    fullscreen: string;
+    exitFullscreen: string;
+    /** Shown when the media cannot be played. */
+    error: string;
+    /** Spoken position, e.g. "1 minute 5 seconds of 4 minutes". */
+    position: (current: string, total: string) => string;
+}
+export declare const defaultMediaLabels: MediaPlayerLabels;

package/dist/internal/media/labels.js

@@ -0,0 +1,15 @@
+export const defaultMediaLabels = {
+    play: 'Play',
+    pause: 'Pause',
+    mute: 'Mute',
+    unmute: 'Unmute',
+    seek: 'Seek',
+    volume: 'Volume',
+    speed: 'Playback speed',
+    captions: 'Captions',
+    pictureInPicture: 'Picture in picture',
+    fullscreen: 'Full screen',
+    exitFullscreen: 'Exit full screen',
+    error: 'This media could not be played.',
+    position: (current, total) => `${current} of ${total}`,
+};

package/dist/internal/options.d.ts

@@ -0,0 +1,9 @@
+import type { Option, OptionGroup } from '../types.js';
+export type OptionEntry<T extends string = string> = Option<T> | OptionGroup<T>;
+export declare const isOptionGroup: <T extends string>(entry: OptionEntry<T>) => entry is OptionGroup<T>;
+/** Every option, groups flattened, with a group's `disabled` pushed down onto its members. */
+export declare const flattenOptions: <T extends string>(entries: readonly OptionEntry<T>[]) => Option<T>[];
+/** Keeps the entries whose options match, dropping groups left empty. */
+export declare const filterEntries: <T extends string>(entries: readonly OptionEntry<T>[], keep: (option: Option<T>) => boolean) => OptionEntry<T>[];
+/** Case- and accent-insensitive substring match on the label. */
+export declare const matchesQuery: (option: Option, query: string) => boolean;

package/dist/internal/options.js

@@ -0,0 +1,20 @@
+export const isOptionGroup = (entry) => 'options' in entry;
+/** Every option, groups flattened, with a group's `disabled` pushed down onto its members. */
+export const flattenOptions = (entries) => entries.flatMap((entry) => isOptionGroup(entry)
+    ? entry.options.map((option) => (entry.disabled ? { ...option, disabled: true } : option))
+    : [entry]);
+/** Keeps the entries whose options match, dropping groups left empty. */
+export const filterEntries = (entries, keep) => entries.flatMap((entry) => {
+    if (!isOptionGroup(entry))
+        return keep(entry) ? [entry] : [];
+    const options = entry.options.filter(keep);
+    return options.length ? [{ ...entry, options }] : [];
+});
+/** Case- and accent-insensitive substring match on the label. */
+export const matchesQuery = (option, query) => {
+    const fold = (value) => value
+        .normalize('NFD')
+        .replace(/\p{Diacritic}/gu, '')
+        .toLocaleLowerCase();
+    return fold(option.label).includes(fold(query.trim()));
+};

package/dist/media-player.svelte.d.ts

@@ -0,0 +1,61 @@
+import type { Attachment } from 'svelte/attachments';
+export interface MediaPlayerOptions {
+    onEnded?: () => void;
+    onError?: (error: MediaError | null) => void;
+    onTimeUpdate?: (seconds: number) => void;
+}
+export interface MediaTrackInfo {
+    label: string;
+    language: string;
+    kind: string;
+}
+export interface MediaPlayer {
+    /** Put on the `<video>` or `<audio>` element: `{@attach player.attach}`. */
+    readonly attach: Attachment<HTMLMediaElement>;
+    readonly playing: boolean;
+    readonly ended: boolean;
+    /** Stalled waiting for data. */
+    readonly waiting: boolean;
+    readonly currentTime: number;
+    /** `NaN` until metadata loads; `Infinity` for a live stream. */
+    readonly duration: number;
+    /** Buffered time ranges, in seconds. */
+    readonly buffered: Array<[number, number]>;
+    readonly volume: number;
+    readonly muted: boolean;
+    readonly rate: number;
+    readonly error: MediaError | null;
+    readonly fullscreen: boolean;
+    readonly pictureInPicture: boolean;
+    /** Captions and subtitles, in document order. */
+    readonly tracks: MediaTrackInfo[];
+    /** Index into `tracks` of the one showing, or `null`. */
+    readonly activeTrack: number | null;
+    /** Whether this browser offers picture-in-picture for the attached element. */
+    readonly canPictureInPicture: boolean;
+    play(): Promise<void>;
+    pause(): void;
+    toggle(): Promise<void>;
+    seek(seconds: number): void;
+    seekBy(delta: number): void;
+    setVolume(volume: number): void;
+    toggleMute(): void;
+    setRate(rate: number): void;
+    /** Show one text track (by index into `tracks`) or none. */
+    selectTrack(index: number | null): void;
+    /** Fullscreen the given container (so custom controls come along), else the media itself. */
+    toggleFullscreen(container?: HTMLElement | null): Promise<void>;
+    togglePictureInPicture(): Promise<void>;
+    destroy(): void;
+}
+/**
+ * Reactive state and commands over a native `<video>` or `<audio>` element. `VideoPlayer` and
+ * `AudioPlayer` are built on it; use it directly to put your own controls on a media element.
+ *
+ * ```svelte
+ * const player = createMediaPlayer();
+ * <video src={url} {@attach player.attach}></video>
+ * <button onclick={player.toggle}>{player.playing ? 'Pause' : 'Play'}</button>
+ * ```
+ */
+export declare function createMediaPlayer(options?: MediaPlayerOptions): MediaPlayer;

package/dist/media-player.svelte.js

@@ -0,0 +1,246 @@
+import { onDestroy } from 'svelte';
+import { clamp, timeRangesToArray } from './media-utils.js';
+/**
+ * Reactive state and commands over a native `<video>` or `<audio>` element. `VideoPlayer` and
+ * `AudioPlayer` are built on it; use it directly to put your own controls on a media element.
+ *
+ * ```svelte
+ * const player = createMediaPlayer();
+ * <video src={url} {@attach player.attach}></video>
+ * <button onclick={player.toggle}>{player.playing ? 'Pause' : 'Play'}</button>
+ * ```
+ */
+export function createMediaPlayer(options = {}) {
+    // Not reactive on purpose: the attachment reads it, and an attachment that reads state it
+    // also writes re-runs itself forever.
+    let media = null;
+    let pipSupported = $state(false);
+    let playing = $state(false);
+    let ended = $state(false);
+    let waiting = $state(false);
+    let currentTime = $state(0);
+    let duration = $state(Number.NaN);
+    let buffered = $state([]);
+    let volume = $state(1);
+    let muted = $state(false);
+    let rate = $state(1);
+    let error = $state(null);
+    let fullscreen = $state(false);
+    let pictureInPicture = $state(false);
+    let tracks = $state([]);
+    let activeTrack = $state(null);
+    const textTracks = () => [...(media?.textTracks ?? [])].filter((track) => track.kind === 'captions' || track.kind === 'subtitles');
+    let detach;
+    const attach = (node) => {
+        media = node;
+        pipSupported =
+            node instanceof HTMLVideoElement &&
+                node.ownerDocument.pictureInPictureEnabled === true &&
+                typeof node.requestPictureInPicture === 'function';
+        const doc = node.ownerDocument;
+        const syncTracks = () => {
+            const list = textTracks();
+            tracks = list.map((track) => ({
+                label: track.label,
+                language: track.language,
+                kind: track.kind,
+            }));
+            const showing = list.findIndex((track) => track.mode === 'showing');
+            activeTrack = showing === -1 ? null : showing;
+        };
+        const sync = () => {
+            playing = !node.paused;
+            ended = node.ended;
+            currentTime = node.currentTime;
+            duration = node.duration;
+            buffered = timeRangesToArray(node.buffered);
+            volume = node.volume;
+            muted = node.muted;
+            rate = node.playbackRate;
+        };
+        const handlers = {
+            play: () => {
+                playing = true;
+                ended = false;
+            },
+            pause: () => (playing = false),
+            playing: () => (waiting = false),
+            waiting: () => (waiting = true),
+            ended: () => {
+                playing = false;
+                ended = true;
+                options.onEnded?.();
+            },
+            timeupdate: () => {
+                currentTime = node.currentTime;
+                options.onTimeUpdate?.(node.currentTime);
+            },
+            durationchange: () => (duration = node.duration),
+            loadedmetadata: () => {
+                sync();
+                syncTracks();
+            },
+            progress: () => (buffered = timeRangesToArray(node.buffered)),
+            volumechange: () => {
+                volume = node.volume;
+                muted = node.muted;
+            },
+            ratechange: () => (rate = node.playbackRate),
+            seeked: () => (currentTime = node.currentTime),
+            error: () => {
+                error = node.error;
+                options.onError?.(node.error);
+            },
+            enterpictureinpicture: () => (pictureInPicture = true),
+            leavepictureinpicture: () => (pictureInPicture = false),
+        };
+        const onFullscreen = () => {
+            const element = doc.fullscreenElement;
+            fullscreen = Boolean(element && (element === node || element.contains(node)));
+        };
+        sync();
+        syncTracks();
+        for (const [type, handler] of Object.entries(handlers))
+            node.addEventListener(type, handler);
+        node.textTracks?.addEventListener?.('change', syncTracks);
+        node.textTracks?.addEventListener?.('addtrack', syncTracks);
+        doc.addEventListener('fullscreenchange', onFullscreen);
+        detach = () => {
+            for (const [type, handler] of Object.entries(handlers)) {
+                node.removeEventListener(type, handler);
+            }
+            node.textTracks?.removeEventListener?.('change', syncTracks);
+            node.textTracks?.removeEventListener?.('addtrack', syncTracks);
+            doc.removeEventListener('fullscreenchange', onFullscreen);
+            if (media === node)
+                media = null;
+            detach = undefined;
+        };
+        return () => detach?.();
+    };
+    async function play() {
+        if (!media)
+            return;
+        try {
+            await media.play();
+        }
+        catch {
+            // Autoplay policy or an unplayable source; `error` and `playing` already say what happened.
+        }
+    }
+    function seek(seconds) {
+        if (!media)
+            return;
+        const end = Number.isFinite(media.duration) ? media.duration : Number.MAX_SAFE_INTEGER;
+        media.currentTime = clamp(seconds, 0, end);
+        currentTime = media.currentTime;
+    }
+    const destroy = () => {
+        detach?.();
+    };
+    try {
+        onDestroy(destroy);
+    }
+    catch {
+        /* module scope: the caller owns `destroy()` */
+    }
+    return {
+        attach,
+        get playing() {
+            return playing;
+        },
+        get ended() {
+            return ended;
+        },
+        get waiting() {
+            return waiting;
+        },
+        get currentTime() {
+            return currentTime;
+        },
+        get duration() {
+            return duration;
+        },
+        get buffered() {
+            return buffered;
+        },
+        get volume() {
+            return volume;
+        },
+        get muted() {
+            return muted;
+        },
+        get rate() {
+            return rate;
+        },
+        get error() {
+            return error;
+        },
+        get fullscreen() {
+            return fullscreen;
+        },
+        get pictureInPicture() {
+            return pictureInPicture;
+        },
+        get tracks() {
+            return tracks;
+        },
+        get activeTrack() {
+            return activeTrack;
+        },
+        get canPictureInPicture() {
+            return pipSupported;
+        },
+        play,
+        pause: () => media?.pause(),
+        toggle: () => (media && !media.paused ? Promise.resolve(media.pause()) : play()),
+        seek,
+        seekBy: (delta) => seek((media?.currentTime ?? 0) + delta),
+        setVolume(next) {
+            if (!media)
+                return;
+            media.volume = clamp(next, 0, 1);
+            if (media.volume > 0 && media.muted)
+                media.muted = false;
+        },
+        toggleMute() {
+            if (media)
+                media.muted = !media.muted;
+        },
+        setRate(next) {
+            if (media)
+                media.playbackRate = clamp(next, 0.25, 4);
+        },
+        selectTrack(index) {
+            textTracks().forEach((track, position) => {
+                track.mode = position === index ? 'showing' : 'disabled';
+            });
+            activeTrack = index;
+        },
+        async toggleFullscreen(container) {
+            if (!media)
+                return;
+            const doc = media.ownerDocument;
+            if (doc.fullscreenElement) {
+                await doc.exitFullscreen?.();
+                return;
+            }
+            const target = container ?? media;
+            if (typeof target.requestFullscreen === 'function')
+                await target.requestFullscreen();
+            // iOS Safari only fullscreens the video element itself.
+            else
+                media.webkitEnterFullscreen?.();
+        },
+        async togglePictureInPicture() {
+            if (!(media instanceof HTMLVideoElement))
+                return;
+            const doc = media.ownerDocument;
+            if (doc.pictureInPictureElement)
+                await doc.exitPictureInPicture();
+            else
+                await media.requestPictureInPicture?.();
+        },
+        destroy,
+    };
+}

package/dist/media-utils.d.ts

@@ -0,0 +1,112 @@
+import { aspectRatio } from '@loidolt/theme-tokens';
+/** One source for a `<video>` or `<audio>`: the browser plays the first it supports. */
+export interface MediaSourceEntry {
+    src: string;
+    /** MIME type. Guessed from the extension when missing. */
+    type?: string;
+}
+/** Captions, subtitles or chapters for a video. */
+export interface MediaTextTrack {
+    src: string;
+    kind?: 'captions' | 'subtitles' | 'descriptions' | 'chapters';
+    /** BCP 47 language tag, e.g. `en`. */
+    srclang: string;
+    label: string;
+    default?: boolean;
+}
+export type MediaKind = 'image' | 'video' | 'audio' | 'embed';
+export type AspectRatioName = keyof typeof aspectRatio;
+export type EmbedProvider = 'youtube' | 'vimeo';
+interface MediaItemBase {
+    /** Stable key. Defaults to the source. */
+    id?: string;
+    /** Shown under the item in a lightbox or carousel. */
+    caption?: string;
+    /** A small preview for grids and filmstrips. Images fall back to their own `src`. */
+    thumbnail?: string;
+}
+export interface ImageMediaItem extends MediaItemBase {
+    kind: 'image';
+    src: string;
+    /** Required; `''` for a purely decorative image. */
+    alt: string;
+    srcset?: string;
+    /** Link to the full-size file, for a lightbox's download button. */
+    download?: string;
+}
+export interface VideoMediaItem extends MediaItemBase {
+    kind: 'video';
+    src: string | MediaSourceEntry[];
+    /** Names the video for assistive tech and in a grid. */
+    title: string;
+    poster?: string;
+    tracks?: MediaTextTrack[];
+}
+export interface AudioMediaItem extends MediaItemBase {
+    kind: 'audio';
+    src: string | MediaSourceEntry[];
+    title: string;
+    artist?: string;
+    artwork?: string;
+}
+export interface EmbedMediaItem extends MediaItemBase {
+    kind: 'embed';
+    /** A YouTube or Vimeo page or share URL. */
+    url: string;
+    title: string;
+    poster?: string;
+}
+export type MediaItem = ImageMediaItem | VideoMediaItem | AudioMediaItem | EmbedMediaItem;
+export declare const clamp: (value: number, min: number, max: number) => number;
+/** A named frame (`'video'`) or any number or `'4 / 3'` string, as a width-over-height number. */
+export declare function resolveAspectRatio(ratio: AspectRatioName | number | string): number;
+/** `75` → `1:15`; `3725` → `1:02:05`. */
+export declare function formatDuration(seconds: number): string;
+/** `75` → `1 minute 15 seconds` — for `aria-valuetext`, where `1:15` is read as a ratio. */
+export declare function formatDurationSpoken(seconds: number): string;
+/** The lower-cased extension of a URL's last path segment, ignoring query and hash. */
+export declare function fileExtension(url: string): string;
+/** A MIME type for a file extension, when it is a media type this library knows. */
+export declare function guessMimeType(extension: string): string | undefined;
+/** What a URL most likely points at, from its MIME type, embed host or extension. */
+export declare function inferMediaKind(url: string, mimeType?: string): MediaKind | null;
+/** Whether a source is an HLS playlist (`.m3u8` or an HLS MIME type). */
+export declare function isHlsSource(source: string | MediaSourceEntry): boolean;
+/** Normalises a `src` prop to a list of typed sources. */
+export declare function toMediaSources(src: string | MediaSourceEntry[]): MediaSourceEntry[];
+/** A `TimeRanges` object (e.g. `media.buffered`) as plain `[start, end]` pairs. */
+export declare function timeRangesToArray(ranges: TimeRanges | null | undefined): Array<[number, number]>;
+export interface ParsedEmbed {
+    provider: EmbedProvider;
+    videoId: string;
+    /** Start offset in seconds, from a `t=` / `start=` parameter or a `#t=` fragment. */
+    start?: number;
+}
+/**
+ * Reads a YouTube or Vimeo page, share or embed URL. Returns `null` for anything else, so an
+ * arbitrary string can be tested safely.
+ */
+export declare function parseEmbedUrl(url: string): ParsedEmbed | null;
+export interface EmbedSrcOptions {
+    /**
+     * Use the provider's no-tracking mode — `youtube-nocookie.com`, Vimeo's `dnt=1`. Defaults to
+     * `true`.
+     */
+    privacy?: boolean;
+    autoplay?: boolean;
+    start?: number;
+}
+/** The iframe `src` for a provider's player. */
+export declare function buildEmbedSrc(provider: EmbedProvider, videoId: string, { privacy, autoplay, start }?: EmbedSrcOptions): string;
+/**
+ * YouTube's own still for a video. Loading it contacts Google before the user presses play, so
+ * `MediaEmbed` never fetches it by itself — pass it as `poster` only if that is acceptable.
+ */
+export declare function embedThumbnail(provider: EmbedProvider, videoId: string): string | null;
+/** The preview image for a media item, if it has one. */
+export declare function mediaThumbnail(item: MediaItem): string | undefined;
+/** A human name for a media item: its title, alt text or caption. */
+export declare function mediaLabel(item: MediaItem, index?: number): string;
+/** A stable key for a media item. */
+export declare function mediaKey(item: MediaItem, index: number): string;
+export {};