@classic-homes/theme-svelte 1.2.3 → 1.3.0

package/dist/lib/index.d.ts

@@ -58,7 +58,9 @@ export { default as Signature } from './components/Signature.svelte';
 export { default as DataTable } from './components/DataTable.svelte';
 export { default as Tabs } from './components/Tabs.svelte';
 export { default as TabPanel } from './components/TabPanel.svelte';
-export type { DropdownMenuItem, DropdownMenuGroup, SelectOption, SelectGroup, Tab, FileMetadata, DataTableColumn, DataTableFilterFn, DataTableFilterOption, RadioOption, ComboboxOption, MultiSelectOption, SignatureData, SignatureStroke, SignaturePoint, SignatureMetadata, SignatureFont, SignatureValidationResult, } from './types/components.js';
+export { AspectRatio, Image, Video, Audio, MediaEmbed, MediaGrid, MediaCarousel, Lightbox, } from './components/media/index.js';
+export type { MediaGridColumns } from './components/media/MediaGrid.svelte';
+export type { DropdownMenuItem, DropdownMenuGroup, SelectOption, SelectGroup, Tab, FileMetadata, DataTableColumn, DataTableFilterFn, DataTableFilterOption, RadioOption, ComboboxOption, MultiSelectOption, SignatureData, SignatureStroke, SignaturePoint, SignatureMetadata, SignatureFont, SignatureValidationResult, MediaKind, MediaEmbedProvider, MediaSource, MediaTextTrack, MediaItemBase, ImageMediaItem, VideoMediaItem, AudioMediaItem, EmbedMediaItem, MediaItem, MediaAspectRatio, MediaFit, CloudflareStreamAccount, MatterportPlayerOptions, } from './types/components.js';
 export { createDataTable, type DataTableOptions, type DataTableRow, type DataTableInstance, type ColumnMeta, type BaseColumnMeta, type DataColumnMeta, type FilterableColumnMeta, type SelectionColumnMeta, type RowSelectionState, type ColumnVisibilityState, type ColumnFiltersState, type PaginationState, type DataTableProps, type DataTableCoreProps, type DataTablePaginationProps, type InferRowType, type FormatResult, getAlignClass, formatCellValue, getColumnValue, defaultGetRowId, DataTableToolbar, DataTableSearch, DataTableColumnVisibility, DataTableColumnFilter, DataTableFacetedFilter, DataTablePagination, DataTableVirtual, DataTableEditableCell, } from './components/data-table/index.js';
 export { default as LogoMain } from './components/LogoMain.svelte';
 export { default as LoadingLogo } from './components/LoadingLogo.svelte';
@@ -88,9 +90,13 @@ export type { PanelEdge, PanelMode, PanelVariant, SnapPoint, CardConfig, Positio
 export { cn } from './utils.js';
 export { parseDate, toISOString, formatDate, formatDateTime, isSameDay } from './utils/date.js';
 export { generateId, computeDescribedBy } from './utils/form.js';
+export { formatDuration, formatDurationSpoken, inferMediaKind, parseEmbedUrl, buildEmbedSrc, getEmbedThumbnail, getMediaThumbnail, getMediaLabel, isTimeBasedMedia, isSpatialMedia, isHlsSource, resolveAspectRatio, toMediaSources, HLS_MIME_TYPE, DASH_MIME_TYPE, type ParsedEmbed, type EmbedSrcOptions, } from './utils/media.js';
+export { cloudflareStream, cloudflareStreamUrls, cloudflareStreamThumbnail, cloudflareStreamHost, type CloudflareStreamItemOptions, type CloudflareStreamUrlOptions, type CloudflareStreamUrls, type CloudflareStreamThumbnailOptions, } from './utils/media.js';
+export { matterportTour, buildMatterportSrc, fetchMatterportMetadata, type MatterportTourOptions, type MatterportMetadata, } from './utils/media.js';
+export { setHlsLoader, hasHlsLoader, loadHls, canPlayHlsNatively, type HlsLoader, type HlsConstructor, type HlsInstance, } from './utils/hls.js';
 export { tv, type VariantProps } from 'tailwind-variants';
 export { validateNonEmptyArray, validateRequired, validateOneOf, validateRange, validateProps, createValidator, type ValidationResult, } from './validation.js';
 export { perfStart, perfEnd, measure, measureAsync, getPerformanceEntries, clearPerformanceEntries, createPerfMonitor, type PerformanceMark, } from './performance.js';
-export { useForm, useAsync, runAsync, usePersistedForm, useFocusTrap, useFocusRef, useReducedMotion, useArrowNavigation, useRovingTabindex, useAnnounce, useEscapeKey, useClickOutside, clickOutsideAction, type UseFormOptions, type UseFormReturn, type FieldError, type FormState, type InferFormData, type UseAsyncOptions, type UseAsyncReturn, type UsePersistedFormOptions, type UsePersistedFormReturn, type InferPersistedFormData, type UseFocusTrapOptions, type UseFocusRefOptions, type UseArrowNavigationOptions, type ArrowNavigationOrientation, type UseRovingTabindexOptions, type UseAnnounceOptions, type UseAnnounceReturn, type UseEscapeKeyOptions, type UseClickOutsideOptions, } from './composables/index.js';
+export { useForm, useAsync, runAsync, usePersistedForm, useFocusTrap, useFocusRef, useReducedMotion, useArrowNavigation, useRovingTabindex, useAnnounce, useMediaPlayer, useMediaZoom, useHlsSource, useEscapeKey, useClickOutside, clickOutsideAction, type UseFormOptions, type UseFormReturn, type FieldError, type FormState, type InferFormData, type UseAsyncOptions, type UseAsyncReturn, type UsePersistedFormOptions, type UsePersistedFormReturn, type InferPersistedFormData, type UseFocusTrapOptions, type UseFocusRefOptions, type UseArrowNavigationOptions, type ArrowNavigationOrientation, type UseRovingTabindexOptions, type UseAnnounceOptions, type UseAnnounceReturn, type UseEscapeKeyOptions, type UseClickOutsideOptions, type UseMediaPlayerOptions, type MediaPlayerApi, type MediaTimeRange, type MediaTrackInfo, type UseMediaZoomOptions, type MediaZoomApi, type UseHlsSourceOptions, type HlsSourceApi, type HlsStatus, } from './composables/index.js';
 export * from './schemas/index.js';
 export { type Notice, type NoticeConfig, type NoticeLocation, type NoticeVariant, type NoticePage, type ActiveNotice, NoticeSchema, NoticeLinkSchema, validateNotice, validateNotices, initializeNotices, setCurrentPath, dismissNotice, clearDismissedNotices, isNoticeDismissed, activeNotices, bannerNotices, cardNotices, getNoticesForPage, refreshNotices, cleanupDismissedNotices, isNoticeActive, isNoticeForPage, isNoticeForLocation, sanitizeHtml, initSanitizer, NoticeBanner, NoticeCard, } from './notices/index.js';

package/dist/lib/index.js

@@ -70,6 +70,8 @@ export { default as DataTable } from './components/DataTable.svelte';
 // Tabs
 export { default as Tabs } from './components/Tabs.svelte';
 export { default as TabPanel } from './components/TabPanel.svelte';
+// Media Components
+export { AspectRatio, Image, Video, Audio, MediaEmbed, MediaGrid, MediaCarousel, Lightbox, } from './components/media/index.js';
 // DataTable sub-components and utilities
 export { 
 // Core state management (native Svelte 5 runes)
@@ -113,6 +115,15 @@ export { cn } from './utils.js';
 export { parseDate, toISOString, formatDate, formatDateTime, isSameDay } from './utils/date.js';
 // Form utilities
 export { generateId, computeDescribedBy } from './utils/form.js';
+// Media utilities
+export { formatDuration, formatDurationSpoken, inferMediaKind, parseEmbedUrl, buildEmbedSrc, getEmbedThumbnail, getMediaThumbnail, getMediaLabel, isTimeBasedMedia, isSpatialMedia, isHlsSource, resolveAspectRatio, toMediaSources, HLS_MIME_TYPE, DASH_MIME_TYPE, } from './utils/media.js';
+// Cloudflare Stream helpers
+export { cloudflareStream, cloudflareStreamUrls, cloudflareStreamThumbnail, cloudflareStreamHost, } from './utils/media.js';
+// Matterport 3D tours
+export { matterportTour, buildMatterportSrc, fetchMatterportMetadata, } from './utils/media.js';
+// HLS support — hls.js is an optional peer dependency; register a loader once
+// at app startup to enable adaptive streams outside Safari
+export { setHlsLoader, hasHlsLoader, loadHls, canPlayHlsNatively, } from './utils/hls.js';
 // Re-export tailwind-variants types for consumer convenience
 export { tv } from 'tailwind-variants';
 // Validation utilities (dev-only, tree-shaken in production)
@@ -122,7 +133,9 @@ export { perfStart, perfEnd, measure, measureAsync, getPerformanceEntries, clear
 // Composables - reusable Svelte 5 state management patterns
 export { useForm, useAsync, runAsync, usePersistedForm, 
 // Accessibility composables
-useFocusTrap, useFocusRef, useReducedMotion, useArrowNavigation, useRovingTabindex, useAnnounce, useEscapeKey, useClickOutside, clickOutsideAction, } from './composables/index.js';
+useFocusTrap, useFocusRef, useReducedMotion, useArrowNavigation, useRovingTabindex, useAnnounce, 
+// Media composables
+useMediaPlayer, useMediaZoom, useHlsSource, useEscapeKey, useClickOutside, clickOutsideAction, } from './composables/index.js';
 // Validation schemas - Zod schemas for forms and data validation
 export * from './schemas/index.js';
 // Notice System - Scheduled, page-specific, dismissible announcements

package/dist/lib/types/components.d.ts

@@ -60,6 +60,12 @@ export interface FileMetadata {
     error?: string;
     /** Whether the file is currently uploading */
     uploading?: boolean;
+    /** Playback duration in seconds, for audio and video files */
+    duration?: number;
+    /** Intrinsic width in pixels, for images and video */
+    width?: number;
+    /** Intrinsic height in pixels, for images and video */
+    height?: number;
 }
 /**
  * DataTable Types
@@ -205,3 +211,169 @@ export interface SignatureValidationResult {
     valid: boolean;
     error?: string;
 }
+/**
+ * Media Types
+ */
+/** The kind of media an item represents */
+export type MediaKind = 'image' | 'video' | 'audio' | 'embed';
+/**
+ * Third-party providers supported by MediaEmbed.
+ *
+ * `matterport` embeds an interactive 3D space rather than a video, so it has
+ * no timeline: it shows no play affordance or duration in grids and strips.
+ */
+export type MediaEmbedProvider = 'youtube' | 'vimeo' | 'cloudflare' | 'matterport';
+/**
+ * Location of a Cloudflare Stream account.
+ *
+ * Supply `customerCode` (the `customer-<CODE>` part of the subdomain shown in
+ * the Stream dashboard), or `domain` when Stream is served from a custom
+ * hostname.
+ */
+export interface CloudflareStreamAccount {
+    /** Customer code from the Stream dashboard */
+    customerCode?: string;
+    /** Full hostname, when serving Stream from a custom domain */
+    domain?: string;
+}
+/** A single `<source>` entry for a video or audio element */
+export interface MediaSource {
+    /** Source URL */
+    src: string;
+    /** MIME type, e.g. `video/mp4` — lets the browser skip sources it cannot play */
+    type?: string;
+}
+/** A `<track>` entry providing captions, subtitles, or descriptions */
+export interface MediaTextTrack {
+    /** URL of the WebVTT file */
+    src: string;
+    /** Track kind (defaults to `subtitles`) */
+    kind?: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
+    /** BCP 47 language tag, e.g. `en` */
+    srclang: string;
+    /** Human-readable label shown in the captions menu */
+    label: string;
+    /** Whether this track is enabled by default */
+    default?: boolean;
+}
+/** Fields shared by every media item */
+export interface MediaItemBase {
+    /** Unique identifier, used as the keyed-each key */
+    id: string;
+    /** Short title shown in the lightbox and used as an accessible name */
+    title?: string;
+    /** Longer caption shown beneath the media */
+    caption?: string;
+    /** Thumbnail URL used in grids, carousels, and thumbnail strips */
+    thumbnail?: string;
+}
+/** An image item */
+export interface ImageMediaItem extends MediaItemBase {
+    kind: 'image';
+    /** Image URL */
+    src: string;
+    /** Alternative text — required; use an empty string only for decorative images */
+    alt: string;
+    /** Responsive candidate list */
+    srcset?: string;
+    /** Sizes attribute paired with `srcset` */
+    sizes?: string;
+    /** Low-resolution placeholder (typically a data URL) blurred in while loading */
+    placeholder?: string;
+    /** Intrinsic width in pixels — set it to reserve layout space */
+    width?: number;
+    /** Intrinsic height in pixels — set it to reserve layout space */
+    height?: number;
+    /** Download URL, when it differs from `src` */
+    downloadUrl?: string;
+}
+/** A self-hosted video item */
+export interface VideoMediaItem extends MediaItemBase {
+    kind: 'video';
+    /** A single URL, or several sources for format fallback */
+    src: string | MediaSource[];
+    /** Poster image shown before playback starts */
+    poster?: string;
+    /** Caption and subtitle tracks */
+    tracks?: MediaTextTrack[];
+    /** Known duration in seconds, shown before metadata loads */
+    duration?: number;
+    /** Download URL, when downloads are offered */
+    downloadUrl?: string;
+}
+/** A self-hosted audio item */
+export interface AudioMediaItem extends MediaItemBase {
+    kind: 'audio';
+    /** A single URL, or several sources for format fallback */
+    src: string | MediaSource[];
+    /** Performer or author, shown beside the title */
+    artist?: string;
+    /** Artwork image URL */
+    artwork?: string;
+    /** Caption and transcript tracks */
+    tracks?: MediaTextTrack[];
+    /** Known duration in seconds, shown before metadata loads */
+    duration?: number;
+    /** Download URL, when downloads are offered */
+    downloadUrl?: string;
+}
+/**
+ * Options for the Matterport showcase player.
+ *
+ * Matterport's own defaults are left alone unless an option asks otherwise,
+ * so an embed looks the way the space's owner configured it.
+ */
+export interface MatterportPlayerOptions {
+    /** Start the space moving as soon as it loads */
+    autoplay?: boolean;
+    /** Load a lightweight first view so the space is explorable sooner (default `true`) */
+    quickStart?: boolean;
+    /** Show Matterport's "Presented by" branding and contact details (default `true`) */
+    brand?: boolean;
+    /** Show the in-player help button (default `true`) */
+    help?: boolean;
+    /** Show the highlight reel along the bottom (default `true`) */
+    highlightReel?: boolean;
+    /** Show the VR button (default `true`) */
+    vr?: boolean;
+    /** Show the floor selector (default `true`) */
+    floorSelector?: boolean;
+    /** Seconds after load before the guided tour starts on its own */
+    guidedTourStart?: number;
+    /** Use the MLS-compliant presentation, which strips branding, links, and VR */
+    mls?: boolean;
+    /** Interface language, as a two-letter code */
+    lang?: string;
+    /**
+     * Any further showcase parameters, passed through untouched. Booleans are
+     * sent as Matterport's `1`/`0`.
+     */
+    params?: Record<string, string | number | boolean>;
+}
+/** A third-party embedded video item */
+export interface EmbedMediaItem extends MediaItemBase, CloudflareStreamAccount {
+    kind: 'embed';
+    /** Hosting provider */
+    provider: MediaEmbedProvider;
+    /**
+     * Provider-specific identifier. The video id for YouTube and Vimeo; for
+     * Cloudflare Stream the video UID, or a signed playback token when the
+     * video is private; for Matterport the space's model id.
+     */
+    videoId: string;
+    /**
+     * Poster image. Derived automatically for YouTube and Cloudflare Stream;
+     * required for Vimeo, whose thumbnails need a network lookup.
+     */
+    poster?: string;
+    /** Start offset in seconds */
+    start?: number;
+    /** Showcase options, for `provider: 'matterport'` */
+    matterport?: MatterportPlayerOptions;
+}
+/** Any item renderable by the media components */
+export type MediaItem = ImageMediaItem | VideoMediaItem | AudioMediaItem | EmbedMediaItem;
+/** Named aspect ratios accepted by AspectRatio and media components */
+export type MediaAspectRatio = 'square' | 'video' | 'photo' | 'portrait' | 'wide';
+/** How media should be fitted into its box */
+export type MediaFit = 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';

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

@@ -0,0 +1,76 @@
+/**
+ * HLS support
+ *
+ * Adaptive streams — Cloudflare Stream among them — are delivered as HLS
+ * playlists. Safari and iOS play those natively; Chrome and Firefox need
+ * `hls.js`.
+ *
+ * `hls.js` is an *optional* peer dependency, and the import that loads it
+ * deliberately lives in application code rather than in this package. A
+ * dynamic `import('hls.js')` written here would be resolved at build time by
+ * every consumer's bundler, so anyone who had not installed hls.js would fail
+ * to build even if they never touched a stream. Registering a loader keeps the
+ * dependency genuinely optional.
+ *
+ * Three ways to provide it, checked in order:
+ *
+ * 1. A loader passed to the component: `<Video hlsLoader={...} />`
+ * 2. A loader registered once at app startup via {@link setHlsLoader}
+ * 3. A global `Hls`, as set by the library's CDN build in a `<script>` tag
+ *
+ * @example Register once at app startup
+ * ```ts
+ * import { setHlsLoader } from '@classic-homes/theme-svelte';
+ *
+ * setHlsLoader(() => import('hls.js').then((m) => m.default));
+ * ```
+ */
+/**
+ * The shape of `hls.js` this package relies on.
+ *
+ * Deliberately structural rather than an `import type` of the real package —
+ * typing against `hls.js` would make it a required dependency for type
+ * checking, which is exactly what an optional peer dependency must avoid.
+ */
+export interface HlsInstance {
+    loadSource(url: string): void;
+    attachMedia(media: HTMLMediaElement): void;
+    destroy(): void;
+    on(event: string, callback: (event: string, data: HlsErrorData) => void): void;
+    startLoad(): void;
+    recoverMediaError(): void;
+}
+/** The error payload hls.js passes to its `hlsError` event. */
+export interface HlsErrorData {
+    type?: string;
+    details?: string;
+    fatal?: boolean;
+}
+/** The `hls.js` default export: a constructor plus a static support probe. */
+export interface HlsConstructor {
+    new (config?: Record<string, unknown>): HlsInstance;
+    isSupported(): boolean;
+    readonly Events: Record<string, string>;
+    readonly ErrorTypes: Record<string, string>;
+}
+/** A function that resolves the `hls.js` constructor. */
+export type HlsLoader = () => Promise<HlsConstructor> | HlsConstructor;
+/**
+ * Register how `hls.js` should be loaded, once, at application startup.
+ *
+ * @example
+ * setHlsLoader(() => import('hls.js').then((m) => m.default));
+ */
+export declare function setHlsLoader(loader: HlsLoader | null): void;
+/** Whether an `hls.js` loader is available, without loading it. */
+export declare function hasHlsLoader(): boolean;
+/**
+ * Resolve the `hls.js` constructor, or `null` when none is available.
+ *
+ * The result is cached, so several players on one page share a single load.
+ */
+export declare function loadHls(loader?: HlsLoader): Promise<HlsConstructor | null>;
+/** Whether the browser can play HLS without `hls.js`. */
+export declare function canPlayHlsNatively(element?: HTMLMediaElement | null): boolean;
+/** Reset the cached loader. Exported for tests. */
+export declare function resetHlsLoader(): void;

package/dist/lib/utils/hls.js

@@ -0,0 +1,83 @@
+/**
+ * HLS support
+ *
+ * Adaptive streams — Cloudflare Stream among them — are delivered as HLS
+ * playlists. Safari and iOS play those natively; Chrome and Firefox need
+ * `hls.js`.
+ *
+ * `hls.js` is an *optional* peer dependency, and the import that loads it
+ * deliberately lives in application code rather than in this package. A
+ * dynamic `import('hls.js')` written here would be resolved at build time by
+ * every consumer's bundler, so anyone who had not installed hls.js would fail
+ * to build even if they never touched a stream. Registering a loader keeps the
+ * dependency genuinely optional.
+ *
+ * Three ways to provide it, checked in order:
+ *
+ * 1. A loader passed to the component: `<Video hlsLoader={...} />`
+ * 2. A loader registered once at app startup via {@link setHlsLoader}
+ * 3. A global `Hls`, as set by the library's CDN build in a `<script>` tag
+ *
+ * @example Register once at app startup
+ * ```ts
+ * import { setHlsLoader } from '@classic-homes/theme-svelte';
+ *
+ * setHlsLoader(() => import('hls.js').then((m) => m.default));
+ * ```
+ */
+let registeredLoader = null;
+let cached = null;
+/**
+ * Register how `hls.js` should be loaded, once, at application startup.
+ *
+ * @example
+ * setHlsLoader(() => import('hls.js').then((m) => m.default));
+ */
+export function setHlsLoader(loader) {
+    registeredLoader = loader;
+    // Drop any cached resolution so a newly registered loader takes effect.
+    cached = null;
+}
+/** Whether an `hls.js` loader is available, without loading it. */
+export function hasHlsLoader() {
+    return registeredLoader !== null || getGlobalHls() !== null;
+}
+function getGlobalHls() {
+    if (typeof globalThis === 'undefined')
+        return null;
+    const candidate = globalThis.Hls;
+    return typeof candidate === 'function' ? candidate : null;
+}
+/**
+ * Resolve the `hls.js` constructor, or `null` when none is available.
+ *
+ * The result is cached, so several players on one page share a single load.
+ */
+export function loadHls(loader) {
+    // A per-call loader bypasses the shared cache; it may differ per component.
+    if (loader) {
+        return Promise.resolve(loader()).catch(() => null);
+    }
+    if (!cached) {
+        const resolved = registeredLoader ?? (() => getGlobalHls());
+        cached = Promise.resolve()
+            .then(() => resolved())
+            .then((ctor) => ctor ?? null)
+            .catch(() => null);
+    }
+    return cached;
+}
+/** Whether the browser can play HLS without `hls.js`. */
+export function canPlayHlsNatively(element) {
+    const probe = element ?? (typeof document === 'undefined' ? null : document.createElement('video'));
+    if (!probe)
+        return false;
+    // Safari answers 'maybe' or 'probably'; everything else answers ''.
+    return (probe.canPlayType('application/vnd.apple.mpegurl') !== '' ||
+        probe.canPlayType('application/x-mpegURL') !== '');
+}
+/** Reset the cached loader. Exported for tests. */
+export function resetHlsLoader() {
+    registeredLoader = null;
+    cached = null;
+}