@classic-homes/theme-svelte 1.2.3 → 1.3.0

package/dist/lib/utils/media.d.ts

@@ -0,0 +1,379 @@
+/**
+ * Media utilities
+ *
+ * Pure helpers shared by the media components. Nothing here touches the DOM or
+ * component state, so it is all directly unit-testable.
+ */
+import type { CloudflareStreamAccount, EmbedMediaItem, MatterportPlayerOptions, MediaAspectRatio, MediaEmbedProvider, MediaItem, MediaKind, MediaSource, MediaTextTrack, VideoMediaItem } from '../types/components.js';
+/** Numeric width/height ratios for the named aspect ratios. */
+export declare const ASPECT_RATIOS: Record<MediaAspectRatio, number>;
+/**
+ * Resolve a ratio prop to a numeric width/height ratio.
+ *
+ * @example
+ * resolveAspectRatio('video') // 1.777…
+ * resolveAspectRatio(2.35)    // 2.35
+ */
+export declare function resolveAspectRatio(ratio: MediaAspectRatio | number): number;
+/**
+ * Format a duration in seconds as `m:ss`, or `h:mm:ss` past an hour.
+ *
+ * Non-finite and negative inputs collapse to `0:00` so a player showing
+ * `NaN` before metadata loads is impossible.
+ *
+ * @example
+ * formatDuration(83)   // '1:23'
+ * formatDuration(3723) // '1:02:03'
+ * formatDuration(NaN)  // '0:00'
+ */
+export declare function formatDuration(seconds: number): string;
+/**
+ * Spoken form of a duration, for `aria-label` and `aria-valuetext`.
+ *
+ * Screen readers announce `1:23` as "one twenty-three", which is ambiguous.
+ *
+ * @example
+ * formatDurationSpoken(83) // '1 minute 23 seconds'
+ */
+export declare function formatDurationSpoken(seconds: number): string;
+/**
+ * Extract the lower-cased file extension from a URL, ignoring query strings
+ * and hash fragments.
+ */
+export declare function getFileExtension(url: string): string;
+/**
+ * Infer a media kind from a URL or MIME type.
+ *
+ * MIME type wins when supplied, since a URL may have no extension at all.
+ * Returns `null` when nothing can be inferred, so callers can decide whether
+ * to fall back or warn.
+ *
+ * @example
+ * inferMediaKind('/clip.mp4')                  // 'video'
+ * inferMediaKind('/asset', 'image/png')        // 'image'
+ * inferMediaKind('https://youtu.be/dQw4w9Wg')  // 'embed'
+ */
+export declare function inferMediaKind(url: string, mimeType?: string): MediaKind | null;
+/** MIME type browsers use for HLS playlists. */
+export declare const HLS_MIME_TYPE = "application/vnd.apple.mpegurl";
+/** MIME type browsers use for MPEG-DASH manifests. */
+export declare const DASH_MIME_TYPE = "application/dash+xml";
+/**
+ * Whether a source is an HLS playlist.
+ *
+ * Checks the declared MIME type first, then the `.m3u8` extension, so a
+ * manifest served from an extensionless or query-laden URL still resolves
+ * correctly as long as its type is declared.
+ */
+export declare function isHlsSource(source: string | MediaSource): boolean;
+/** Normalize a `src` prop to the list of sources a `<video>`/`<audio>` should render. */
+export declare function toMediaSources(src: string | MediaSource[]): MediaSource[];
+/** Best-effort MIME type for a media file extension. */
+export declare function guessMimeType(extension: string): string | undefined;
+/**
+ * Cloudflare Stream
+ *
+ * Stream serves every asset for a video from one host, keyed by the video UID.
+ * A signed playback token substitutes for the UID in exactly the same
+ * position, so private videos need no separate code path — pass the token as
+ * `videoId`.
+ *
+ * @see https://developers.cloudflare.com/stream/viewing-videos/using-own-player/
+ */
+/** Resolve the host serving a Stream account's assets. */
+export declare function cloudflareStreamHost(account: CloudflareStreamAccount): string | null;
+/** Options for a Stream thumbnail image. */
+export interface CloudflareStreamThumbnailOptions extends CloudflareStreamAccount {
+    /** Timestamp to grab, e.g. `1s` or `5m2s` (Stream's default is `0s`) */
+    time?: string;
+    /** Height in pixels (Stream's default is 640) */
+    height?: number;
+    /** Width in pixels (Stream's default is 640) */
+    width?: number;
+    /** How the frame is fitted to the requested box */
+    fit?: 'crop' | 'clip' | 'scale' | 'fill';
+    /** Return an animated GIF instead of a still JPEG */
+    animated?: boolean;
+    /** GIF length, e.g. `4s` (animated only) */
+    duration?: string;
+    /** GIF frame rate (animated only) */
+    fps?: number;
+}
+/**
+ * Thumbnail URL for a Cloudflare Stream video.
+ *
+ * Unlike Vimeo, Stream generates thumbnails on demand from a predictable URL,
+ * so a poster never needs a network lookup to discover.
+ *
+ * @example
+ * cloudflareStreamThumbnail('a1b2c3', { customerCode: 'abc', time: '1s', height: 600 })
+ * // 'https://customer-abc.cloudflarestream.com/a1b2c3/thumbnails/thumbnail.jpg?time=1s&height=600'
+ */
+export declare function cloudflareStreamThumbnail(videoId: string, options: CloudflareStreamThumbnailOptions): string | null;
+/** Options for building Stream playback URLs. */
+export interface CloudflareStreamUrlOptions extends CloudflareStreamAccount {
+    /** Request the low-latency HLS variant */
+    lowLatency?: boolean;
+    /** Bandwidth hint in Mbps, passed to Stream as `clientBandwidthHint` */
+    clientBandwidthHint?: number;
+}
+/** Every playback URL for a Cloudflare Stream video. */
+export interface CloudflareStreamUrls {
+    /** HLS playlist — the source our own player uses */
+    hls: string;
+    /** DASH manifest, for players that prefer it */
+    dash: string;
+    /** Cloudflare's own player, for use in an iframe */
+    iframe: string;
+    /** Still thumbnail */
+    thumbnail: string;
+    /** Pre-encoded MP4, available only when downloads are enabled on the video */
+    download: string;
+}
+/**
+ * Build the playback URLs for a Cloudflare Stream video.
+ *
+ * Returns `null` when the account cannot be resolved, so a missing customer
+ * code surfaces as a clear failure rather than a malformed request.
+ *
+ * @example
+ * cloudflareStreamUrls('a1b2c3', { customerCode: 'abc' })?.hls
+ * // 'https://customer-abc.cloudflarestream.com/a1b2c3/manifest/video.m3u8'
+ */
+export declare function cloudflareStreamUrls(videoId: string, options: CloudflareStreamUrlOptions): CloudflareStreamUrls | null;
+/** Options for {@link cloudflareStream}. */
+export interface CloudflareStreamItemOptions extends CloudflareStreamUrlOptions {
+    /** Item id; defaults to the video id */
+    id?: string;
+    /** Title shown in players, grids, and the lightbox */
+    title?: string;
+    /** Longer caption shown beneath the video */
+    caption?: string;
+    /** Known duration in seconds, shown before metadata loads */
+    duration?: number;
+    /** Override the derived poster */
+    poster?: string;
+    /** Timestamp used for the derived poster, e.g. `1s` */
+    posterTime?: string;
+    /** Height of the derived poster in pixels */
+    posterHeight?: number;
+    /**
+     * Caption tracks. Stream embeds its own captions in the HLS playlist, so
+     * these are only needed for tracks hosted elsewhere.
+     */
+    tracks?: MediaTextTrack[];
+    /** Offer a download link (only works when downloads are enabled on the video) */
+    downloadable?: boolean;
+}
+/**
+ * Build a media item for a Cloudflare Stream video, playable by `Video`,
+ * `MediaGrid`, `MediaCarousel`, and `Lightbox`.
+ *
+ * The item's source is the HLS playlist, so playback uses the design system's
+ * own controls rather than Cloudflare's player. Use `MediaEmbed` with
+ * `provider="cloudflare"` when you want Cloudflare's player instead.
+ *
+ * Throws when the account cannot be resolved, because every URL on the
+ * returned item would otherwise be malformed.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { Video, cloudflareStream } from '@classic-homes/theme-svelte';
+ *
+ *   const tour = cloudflareStream('a1b2c3', {
+ *     customerCode: 'abc123',
+ *     title: 'Product tour',
+ *   });
+ * </script>
+ *
+ * <Video item={tour} />
+ * ```
+ */
+export declare function cloudflareStream(videoId: string, options: CloudflareStreamItemOptions): VideoMediaItem;
+/**
+ * Build the showcase URL for a Matterport space.
+ *
+ * Matterport's own defaults are left alone unless an option asks otherwise,
+ * so the embed looks the way the space's owner configured it.
+ *
+ * @example
+ * buildMatterportSrc('SxQL3iGyoDo', { brand: false })
+ * // 'https://my.matterport.com/show/?m=SxQL3iGyoDo&qs=1&brand=0'
+ */
+export declare function buildMatterportSrc(modelId: string, options?: MatterportPlayerOptions): string;
+/** The public metadata Matterport exposes for a space. */
+export interface MatterportMetadata {
+    /** The space's name, as set by its owner */
+    name: string;
+    /** Preview image URL. Signed and time-limited, so it cannot be cached long. */
+    image: string | null;
+}
+/**
+ * Look up a Matterport space's name and preview image.
+ *
+ * Matterport publishes no oEmbed endpoint and no derivable thumbnail URL, so
+ * a real preview needs this request. It is never made automatically — the
+ * caller opts in — because contacting the provider before the viewer clicks is
+ * exactly what the lazy facade exists to avoid.
+ *
+ * The returned image URL is signed and short-lived, so it must be used
+ * promptly rather than stored.
+ *
+ * Resolves to `null` on any failure rather than throwing, so a preview is
+ * always an enhancement and never breaks a render.
+ */
+export declare function fetchMatterportMetadata(modelId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<MatterportMetadata | null>;
+/** Options for {@link matterportTour}. */
+export interface MatterportTourOptions extends MatterportPlayerOptions {
+    /** Item id; defaults to the model id */
+    id?: string;
+    /** Title shown in players, grids, and the lightbox */
+    title?: string;
+    /** Longer caption shown beneath the tour */
+    caption?: string;
+    /** Preview image. Matterport publishes none, so supply one for a real thumbnail. */
+    poster?: string;
+}
+/**
+ * Build a media item for a Matterport space, usable by `MediaEmbed`,
+ * `MediaGrid`, `MediaCarousel`, and `Lightbox`.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { MediaGrid, matterportTour } from '@classic-homes/theme-svelte';
+ *
+ *   const items = [matterportTour('SxQL3iGyoDo', { title: 'Show home' })];
+ * </script>
+ *
+ * <MediaGrid {items} />
+ * ```
+ */
+export declare function matterportTour(modelId: string, options?: MatterportTourOptions): EmbedMediaItem;
+/** A provider/id pair parsed out of an embed URL. */
+export interface ParsedEmbed {
+    provider: MediaEmbedProvider;
+    videoId: string;
+    /** Start offset in seconds, when the URL carried one */
+    start?: number;
+    /** Stream customer code, when the URL was a Cloudflare Stream URL */
+    customerCode?: string;
+    /** Host, when the URL used a custom Stream domain */
+    domain?: string;
+}
+/**
+ * Parse a YouTube, Vimeo, or Cloudflare Stream URL into a provider and video id.
+ *
+ * Handles `youtube.com/watch?v=`, `youtu.be/`, `/embed/`, `/shorts/`, and
+ * `/live/` for YouTube; `vimeo.com/<id>` (including unlisted-hash and
+ * `player.vimeo.com/video/<id>` forms) for Vimeo; and every
+ * `customer-<CODE>.cloudflarestream.com/<UID>/…` form plus the legacy
+ * `videodelivery.net` hosts for Stream. Returns `null` for anything else
+ * rather than guessing.
+ *
+ * @example
+ * parseEmbedUrl('https://youtu.be/dQw4w9WgXcQ?t=30')
+ * // { provider: 'youtube', videoId: 'dQw4w9WgXcQ', start: 30 }
+ *
+ * @example
+ * parseEmbedUrl('https://customer-abc.cloudflarestream.com/a1b2c3/iframe')
+ * // { provider: 'cloudflare', videoId: 'a1b2c3', customerCode: 'abc' }
+ */
+export declare function parseEmbedUrl(url: string): ParsedEmbed | null;
+/** Options accepted when building an embed iframe URL. */
+export interface EmbedSrcOptions {
+    /** Route YouTube through `youtube-nocookie.com` (default `true`) */
+    privacy?: boolean;
+    /** Begin playing immediately — set when the user has clicked the facade */
+    autoplay?: boolean;
+    /** Start offset in seconds */
+    start?: number;
+    /** Show provider chrome and related-video suggestions (default `false`) */
+    showRelated?: boolean;
+    /** Start muted (Cloudflare Stream) */
+    muted?: boolean;
+    /** Loop playback (Cloudflare Stream) */
+    loop?: boolean;
+    /** Show the provider player's own controls (Cloudflare Stream, default `true`) */
+    controls?: boolean;
+    /** Preload hint for the provider player (Cloudflare Stream) */
+    preload?: 'none' | 'metadata' | 'auto';
+    /** Poster image shown by the provider player (Cloudflare Stream) */
+    poster?: string;
+    /** Accent colour for the player UI, any CSS colour (Cloudflare Stream) */
+    primaryColor?: string;
+    /** Letterbox/pillarbox colour, any CSS colour (Cloudflare Stream) */
+    letterboxColor?: string;
+    /** BCP-47 language code for the captions track to enable (Cloudflare Stream) */
+    defaultTextTrack?: string;
+    /** Stream customer code from the dashboard (Cloudflare Stream) */
+    customerCode?: string;
+    /** Custom Stream hostname (Cloudflare Stream) */
+    domain?: string;
+    /** Showcase options (Matterport) */
+    matterport?: MatterportPlayerOptions;
+}
+/**
+ * Build the iframe `src` for an embedded video.
+ *
+ * YouTube defaults to the `youtube-nocookie.com` domain, which does not set
+ * tracking cookies until playback begins. Cloudflare Stream needs the account
+ * to be resolvable, so pass `customerCode` or `domain` for that provider.
+ *
+ * @example
+ * buildEmbedSrc('youtube', 'dQw4w9WgXcQ', { autoplay: true, start: 30 })
+ * // 'https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?autoplay=1&start=30&rel=0'
+ *
+ * @example
+ * buildEmbedSrc('cloudflare', 'a1b2c3', { customerCode: 'abc' })
+ * // 'https://customer-abc.cloudflarestream.com/a1b2c3/iframe'
+ */
+export declare function buildEmbedSrc(provider: MediaEmbedProvider, videoId: string, options?: EmbedSrcOptions): string;
+/**
+ * Poster image URL for an embedded video, when one can be derived without a
+ * network request.
+ *
+ * YouTube and Cloudflare Stream both expose predictable thumbnail URLs. Vimeo
+ * does not — its thumbnails require an oEmbed lookup — so this returns `null`
+ * and the caller should supply `poster` explicitly.
+ */
+export declare function getEmbedThumbnail(provider: MediaEmbedProvider, videoId: string, account?: CloudflareStreamAccount): string | null;
+/**
+ * Best available thumbnail for a media item, for grids and thumbnail strips.
+ *
+ * Returns `null` when the item has no visual representation (audio without
+ * artwork, video without a poster), so callers can render an icon instead.
+ */
+export declare function getMediaThumbnail(item: MediaItem): string | null;
+/**
+ * Accessible name for a media item.
+ *
+ * Prefers an explicit title, then image alt text, then a positional fallback
+ * so a tile is never announced as just "button".
+ */
+export declare function getMediaLabel(item: MediaItem, index?: number): string;
+/** Whether an item is an interactive 3D space rather than something that plays. */
+export declare function isSpatialMedia(item: MediaItem): boolean;
+/**
+ * Whether an item has a timeline, and so shows a duration badge and play
+ * affordance.
+ *
+ * A Matterport space is embedded like a video but has no timeline — offering
+ * it a play button would promise something the player does not do.
+ */
+export declare function isTimeBasedMedia(item: MediaItem): boolean;
+/**
+ * Flatten a `TimeRanges` object into plain start/end pairs.
+ *
+ * `TimeRanges` is an opaque, non-iterable browser type; this makes buffered
+ * ranges renderable and testable.
+ */
+export declare function timeRangesToArray(ranges: TimeRanges | null): Array<{
+    start: number;
+    end: number;
+}>;
+/** Clamp a number into an inclusive range. */
+export declare function clamp(value: number, min: number, max: number): number;