@retoo/scena 0.0.1 → 0.1.0

package/README.md

@@ -2,9 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/@retoo/scena)](https://www.npmjs.com/package/@retoo/scena)
 [![bundle size](https://img.shields.io/badge/gzipped-~30KB-blue)](https://use-retoo.github.io/scena/distribution/bundle-size)
-[![license](https://img.shields.io/npm/l/@retoo/scena)](./LICENSE.md)
+[![license](https://img.shields.io/badge/license-PolyForm%20Shield%201.0.0-blue)](./LICENSE.md)
 
-Embeddable video widget for any website. Framework-agnostic, SSR-safe, ~26KB gzipped.
+Embeddable video widget for any website. Framework-agnostic, SSR-safe, ~30KB gzipped.
 
 **[Documentation](https://use-retoo.github.io/scena)**
 

package/dist/index.d.ts

@@ -2,8 +2,6 @@ export { default as Scena } from './app/entrypoint/ui/Scena.svelte';
 
 /** Event names emitted by the scena widget event bus. */
 declare enum ScenaEvent {
-    /** Fired when the scena component is mounted in the DOM. */
-    ON_SCENA_MOUNT = "scena:on-mount",
     /** Fired when the scena instance is destroyed. */
     ON_SCENA_DESTROY = "scena:on-destroy",
     /** Fired when the video element is ready for playback. */
@@ -131,6 +129,10 @@ declare enum OverrideLayer {
     PREVIEW = "preview"
 }
 
+/** Shape of any component instance that exposes its DOM elements via `getElements()`. */
+type ComponentRef<T> = {
+    getElements(): T;
+};
 /** Inline styles — a raw CSS string or a partial `CSSStyleDeclaration` object. */
 type ComponentStyles = string | Partial<CSSStyleDeclaration>;
 /**
@@ -186,11 +188,13 @@ interface ScenaContainerProps {
 interface ScenaContainerSnippets {
     children: ComponentSnippet;
 }
+/** DOM elements exposed by the outer container component. */
+interface ScenaContainerElements {
+    root: HTMLDivElement | null;
+}
 /** Component ref for the outer container. */
 interface ScenaContainerRef {
-    getElements: () => {
-        root: HTMLDivElement;
-    };
+    getElements: () => ScenaContainerElements;
 }
 
 /** Possible values for `aria-pressed` on scena buttons. */
@@ -255,7 +259,7 @@ interface ScenaButtonSnippets {
 }
 /** DOM element references for the base button. */
 interface ScenaButtonElements {
-    root: HTMLButtonElement;
+    root: HTMLButtonElement | null;
 }
 
 interface ScenaIconCustomClasses {
@@ -275,7 +279,7 @@ interface ScenaIconSnippets {
     children: ComponentSnippet;
 }
 interface ScenaIconElements {
-    root: SVGSVGElement;
+    root: SVGSVGElement | null;
 }
 
 /** Custom CSS class overrides for the close button and its sub-components. */
@@ -290,6 +294,10 @@ interface ScenaCloseButtonComponentStyles {
     button: ComponentStyles;
     cross: ComponentStyles;
 }
+/** Custom HTML override for the close button. */
+interface ScenaCloseButtonComponentHtml {
+    button: string;
+}
 /** Configuration props for the close button widget. */
 interface ScenaCloseButtonProps {
     id: string;
@@ -298,15 +306,18 @@ interface ScenaCloseButtonProps {
     aria: Partial<ComponentAriaProps>;
     customClasses: Partial<ScenaCloseButtonComponentClasses>;
     customStyles: Partial<ScenaCloseButtonComponentStyles>;
+    customHtml: Partial<ScenaCloseButtonComponentHtml>;
     onClick: (event: Event) => void;
 }
+/** DOM elements exposed by the close button component. */
+interface ScenaCloseButtonElements {
+    root: HTMLDivElement | null;
+    cross: ScenaIconElements | null;
+    button: ScenaButtonElements | null;
+}
 /** Component ref for the close button. */
 interface ScenaCloseButtonRef {
-    getElements: () => {
-        root: HTMLDivElement;
-        button: ScenaButtonElements | undefined;
-        cross: ScenaIconElements | undefined;
-    };
+    getElements: () => ScenaCloseButtonElements;
 }
 
 declare enum ScenaCtaButtonPlacement {
@@ -324,6 +335,10 @@ interface ScenaCtaButtonComponentStyles {
     root: ComponentStyles;
     button: ComponentStyles;
 }
+/** Custom HTML override for the CTA button. */
+interface ScenaCtaButtonComponentHtml {
+    button: string;
+}
 /** Adaptive display settings for the CTA button across screen sizes. */
 interface ScenaCtaButtonAdaptive {
     sizes: ComponentSize[];
@@ -339,14 +354,17 @@ interface ScenaCtaButtonProps {
     aria: Partial<ComponentAriaProps>;
     customClasses: Partial<ScenaCtaButtonComponentClasses>;
     customStyles: Partial<ScenaCtaButtonComponentStyles>;
+    customHtml: Partial<ScenaCtaButtonComponentHtml>;
     onClick: (event: Event) => void;
 }
+/** DOM elements exposed by the CTA button component. */
+interface ScenaCtaButtonElements {
+    root: HTMLDivElement | null;
+    button: ScenaButtonElements | null;
+}
 /** Component ref for the CTA button. */
 interface ScenaCtaButtonRef {
-    getElements: () => {
-        root: HTMLDivElement;
-        button: ScenaButtonElements | undefined;
-    };
+    getElements: () => ScenaCtaButtonElements;
 }
 
 /** Preload strategy for the `<video>` element. */
@@ -491,21 +509,22 @@ interface ScenaVideoSnippets {
 /** Options for creating the video controller. */
 interface UseVideoControllerOptions {
     /** Getter that returns the underlying `<video>` DOM element. */
-    getVideoElement: () => HTMLVideoElement;
+    getVideoElement: () => HTMLVideoElement | null;
     /** Event emitter to broadcast video lifecycle events. */
     eventEmitter: ScenaEventEmitter;
 }
 /** Return value of `useVideoController` — combines reactive data, methods, and callbacks. */
 type UseVideoControllerReturns = ScenaVideoData & ScenaVideoMethods & ScenaVideoCallbacks;
+/** DOM elements exposed by the video widget. */
+interface ScenaVideoElements {
+    root: HTMLDivElement | null;
+    video: HTMLVideoElement | null;
+}
 /** Component ref for the video widget. */
 interface ScenaVideoRef {
     /** Video playback controller. */
     controller: UseVideoControllerReturns;
-    /** Returns references to the root wrapper and video DOM elements. */
-    getElements: () => {
-        root: HTMLDivElement;
-        video: HTMLVideoElement;
-    };
+    getElements: () => ScenaVideoElements;
 }
 
 declare function useVideoController({ getVideoElement, eventEmitter }: UseVideoControllerOptions): UseVideoControllerReturns;
@@ -534,11 +553,13 @@ interface ScenaVideoContainerProps {
 interface ScenaVideoContainerSnippets {
     children: ComponentSnippet;
 }
+/** DOM elements exposed by the video container component. */
+interface ScenaVideoContainerElements {
+    root: HTMLDivElement | null;
+}
 /** Component ref for the video container. */
 interface ScenaVideoContainerRef {
-    getElements: () => {
-        root: HTMLDivElement;
-    };
+    getElements: () => ScenaVideoContainerElements;
 }
 
 /** Custom CSS class overrides for the video play/pause controls. */
@@ -553,6 +574,11 @@ interface ScenaVideoControlsComponentStyles {
     play: ComponentStyles;
     pause: ComponentStyles;
 }
+/** Custom HTML overrides for the video play/pause controls. */
+interface ScenaVideoControlsComponentHtml {
+    play: string;
+    pause: string;
+}
 /** Per-button ARIA overrides for video controls. */
 interface ScenaVideoControlsComponentAria {
     play: Partial<ComponentAriaProps>;
@@ -565,16 +591,19 @@ interface ScenaVideoControlsProps {
     aria: Partial<ScenaVideoControlsComponentAria>;
     customClasses: Partial<ScenaVideoControlsComponentClasses>;
     customStyles: Partial<ScenaVideoControlsComponentStyles>;
+    customHtml: Partial<ScenaVideoControlsComponentHtml>;
+}
+/** DOM elements exposed by the video controls component. */
+interface ScenaVideoControlsElements {
+    root: HTMLDivElement | null;
+    pauseButton: ScenaButtonElements | null;
+    pauseIcon: ScenaIconElements | null;
+    playButton: ScenaButtonElements | null;
+    playIcon: ScenaIconElements | null;
 }
 /** Component ref for the video play/pause controls. */
 interface ScenaVideoControlsRef {
-    getElements: () => {
-        root: HTMLDivElement | null;
-        pauseButton: ScenaButtonElements | undefined;
-        pauseIcon: ScenaIconElements | undefined;
-        playButton: ScenaButtonElements | undefined;
-        playIcon: ScenaIconElements | undefined;
-    };
+    getElements: () => ScenaVideoControlsElements;
 }
 
 /** Custom CSS class overrides for the loader spinner. */
@@ -594,7 +623,7 @@ interface ScenaLoaderProps {
 }
 /** DOM element references for the loader spinner. */
 interface ScenaLoaderElements {
-    root: SVGSVGElement;
+    root: SVGSVGElement | null;
 }
 
 /** Custom CSS class overrides for the video loader widget. */
@@ -607,19 +636,26 @@ interface ScenaVideoLoaderComponentStyles {
     root: ComponentStyles;
     loader: ComponentStyles;
 }
+/** Custom HTML override for the video loader. */
+interface ScenaVideoLoaderComponentHtml {
+    loader: string;
+}
 /** Configuration props for the video buffering/loading indicator. */
 interface ScenaVideoLoaderProps {
     id: string;
     size: ComponentSize;
     customClasses: Partial<ScenaVideoLoaderComponentClasses>;
     customStyles: Partial<ScenaVideoLoaderComponentStyles>;
+    customHtml: Partial<ScenaVideoLoaderComponentHtml>;
+}
+/** DOM elements exposed by the video loader component. */
+interface ScenaVideoLoaderElements {
+    root: HTMLDivElement | null;
+    loader: ScenaLoaderElements | null;
 }
 /** Component ref for the video loader. */
 interface ScenaVideoLoaderRef {
-    getElements: () => {
-        root: HTMLDivElement;
-        loader: ScenaLoaderElements | undefined;
-    };
+    getElements: () => ScenaVideoLoaderElements;
 }
 
 declare enum ScenaVideoProgressVariant {
@@ -722,8 +758,8 @@ interface UseProgressLineReturn {
 /** Props accepted by the line progress hook. */
 interface UseProgressLineProps {
     getRootElement: () => HTMLElement;
-    getSize: () => ComponentSize;
     getCustomThickness: () => ScenaProgressComponentThickness;
+    getSize: () => ComponentSize;
     getProgress: () => number;
 }
 /** Seek event callbacks used internally by the line progress hook. */
@@ -734,9 +770,9 @@ interface UseProgressLineEvents {
 }
 /** Props accepted by the circle progress hook. */
 interface UseProgressCircleProps {
-    getRootElement: () => SVGSVGElement;
-    getSize: () => ComponentSize;
+    getRootElement: () => SVGSVGElement | null;
     getCustomThickness: () => ScenaProgressComponentThickness;
+    getSize: () => ComponentSize;
     getProgress: () => number;
     getBuffer: () => number;
 }
@@ -758,14 +794,14 @@ interface UseProgressCircleReturnEvents {
 }
 /** DOM element references for the linear progress bar. */
 interface ScenaProgressLineElements {
-    root: HTMLDivElement;
+    root: HTMLDivElement | null;
     track: HTMLDivElement;
     buffer: HTMLDivElement | null;
     progress: HTMLDivElement;
 }
 /** DOM element references for the circular progress indicator. */
 interface ScenaProgressCircleElements {
-    root: SVGSVGElement;
+    root: SVGSVGElement | null;
     track: SVGCircleElement | null;
     buffer: SVGCircleElement | null;
     progress: SVGCircleElement | null;
@@ -823,9 +859,13 @@ interface ScenaVideoProgressProps {
     customClasses: Partial<ScenaVideoProgressComponentClasses>;
     customStyles: Partial<ScenaVideoProgressComponentStyles>;
 }
+/** DOM elements exposed by the video progress component. */
+interface ScenaVideoProgressElements {
+    root: ScenaProgressLineElements | ScenaProgressCircleElements | null;
+}
 /** Component ref for the video progress bar. */
 interface ScenaVideoProgressRef {
-    getElements: () => ScenaProgressLineElements | ScenaProgressCircleElements | null;
+    getElements: () => ScenaVideoProgressElements;
 }
 
 /** Custom CSS class overrides for the volume mute/unmute controls. */
@@ -840,6 +880,11 @@ interface ScenaVideoVolumeComponentStyles {
     mute: ComponentStyles;
     unmute: ComponentStyles;
 }
+/** Custom HTML overrides for the volume mute/unmute controls. */
+interface ScenaVideoVolumeComponentHtml {
+    mute: string;
+    unmute: string;
+}
 /** Per-button ARIA overrides for volume controls. */
 interface ScenaVideoVolumeComponentAria {
     mute: Partial<ComponentAriaProps>;
@@ -853,16 +898,19 @@ interface ScenaVideoVolumeProps {
     aria: Partial<ScenaVideoVolumeComponentAria>;
     customClasses: Partial<ScenaVideoVolumeComponentClasses>;
     customStyles: Partial<ScenaVideoVolumeComponentStyles>;
+    customHtml: Partial<ScenaVideoVolumeComponentHtml>;
+}
+/** DOM elements exposed by the volume control component. */
+interface ScenaVideoVolumeElements {
+    root: HTMLDivElement | null;
+    unmuteButton: ScenaButtonElements | null;
+    unmuteIcon: ScenaIconElements | null;
+    muteButton: ScenaButtonElements | null;
+    muteIcon: ScenaIconElements | null;
 }
 /** Component ref for the volume control widget. */
 interface ScenaVideoVolumeRef {
-    getElements: () => {
-        root: HTMLDivElement | null;
-        unmuteButton: ScenaButtonElements | undefined;
-        unmuteIcon: ScenaIconElements | undefined;
-        muteButton: ScenaButtonElements | undefined;
-        muteIcon: ScenaIconElements | undefined;
-    };
+    getElements: () => ScenaVideoVolumeElements;
 }
 
 /** Return value of {@link useScenaOverrides}. */
@@ -1232,4 +1280,4 @@ declare const getScenaContext: () => ScenaContext;
 declare const setScenaContext: (context: ScenaContext) => ScenaContext;
 
 export { ComponentAriaHaspopup, ComponentAriaPressed, ComponentPlacement, ComponentPosition, ComponentShape, ComponentSize, OverrideLayer, ScenaButtonAriaHaspopup, ScenaButtonAriaPressed, ScenaButtonShape, ScenaButtonType, ScenaButtonVariant, ScenaCtaButtonPlacement, ScenaElement, ScenaEvent, ScenaVideoCrossOrigin, ScenaVideoPreload, ScenaVideoProgressVariant, ScenaVideoState, defineScenaElement, getScenaContext, getScenaElement, getScenaVideoContext, scenaProgressCircleThicknessMap, scenaProgressLineThicknessMap, setScenaContext, setScenaVideoContext, useEventEmitter, useProgressCircle, useProgressLine, useScena, useScenaConfig, useScenaOverrides, useScenaPreview, useScenaResponsive, useScenaVisibility, useVideoController };
-export type { ComponentAriaProps, ComponentClasses, ComponentSnippet, ComponentSnippetReturn, ComponentStyles, ScenaApi, ScenaButtonComponentClasses, ScenaButtonComponentStyles, ScenaButtonElements, ScenaButtonEvents, ScenaButtonProps, ScenaButtonSnippets, ScenaCloseButtonComponentClasses, ScenaCloseButtonComponentStyles, ScenaCloseButtonProps, ScenaCloseButtonRef, ScenaComponents, ScenaConfig, ScenaConfigFeatures, ScenaConfigOverrides, ScenaContainerCustomClasses, ScenaContainerCustomStyles, ScenaContainerProps, ScenaContainerRef, ScenaContainerSnippets, ScenaContext, ScenaCtaButtonAdaptive, ScenaCtaButtonComponentClasses, ScenaCtaButtonComponentStyles, ScenaCtaButtonProps, ScenaCtaButtonRef, ScenaElementTag, ScenaEventEmitter, ScenaEventHandler, ScenaEventMap, ScenaFeatures, ScenaIconCustomClasses, ScenaIconCustomStyles, ScenaIconElements, ScenaIconProps, ScenaIconSnippets, ScenaInstance, ScenaLoaderCustomClasses, ScenaLoaderCustomStyles, ScenaLoaderElements, ScenaLoaderProps, ScenaOverrides, ScenaPreviewApi, ScenaPreviewConfig, ScenaProgressCircleComponentClasses, ScenaProgressCircleComponentStyles, ScenaProgressCircleElements, ScenaProgressCircleEvents, ScenaProgressCircleProps, ScenaProgressComponentThickness, ScenaProgressLineComponentClasses, ScenaProgressLineComponentStyles, ScenaProgressLineElements, ScenaProgressLineEvents, ScenaProgressLineProps, ScenaProgressThickness, ScenaProps, ScenaRef, ScenaResponsiveApi, ScenaResponsiveConfig, ScenaTarget, ScenaVideoCallbacks, ScenaVideoComponentClasses, ScenaVideoComponentStyles, ScenaVideoContainerCustomClasses, ScenaVideoContainerCustomStyles, ScenaVideoContainerProps, ScenaVideoContainerRef, ScenaVideoContainerSnippets, ScenaVideoContext, ScenaVideoControlsComponentAria, ScenaVideoControlsComponentClasses, ScenaVideoControlsComponentStyles, ScenaVideoControlsProps, ScenaVideoControlsRef, ScenaVideoData, ScenaVideoEventOptions, ScenaVideoEventOptionsWithError, ScenaVideoEventOptionsWithEvent, ScenaVideoLoaderComponentClasses, ScenaVideoLoaderComponentStyles, ScenaVideoLoaderProps, ScenaVideoLoaderRef, ScenaVideoMethods, ScenaVideoProgressComponentClasses, ScenaVideoProgressComponentStyles, ScenaVideoProgressComponentThickness, ScenaVideoProgressProps, ScenaVideoProgressRef, ScenaVideoProgressThickness, ScenaVideoProgressThicknessMap, ScenaVideoProps, ScenaVideoRef, ScenaVideoSnippets, ScenaVideoVolumeComponentAria, ScenaVideoVolumeComponentClasses, ScenaVideoVolumeComponentStyles, ScenaVideoVolumeProps, ScenaVideoVolumeRef, ScenaVisibilityApi, ScenaVisibilityConfig, UseProgressCircleEvents, UseProgressCircleProps, UseProgressCircleReturn, UseProgressCircleReturnEvents, UseProgressLineEvents, UseProgressLineProps, UseProgressLineReturn, UseProgressLineReturnEvents, UseScenaConfigReturns, UseScenaOverridesReturns, UseScenaPreviewOptions, UseScenaPreviewReturns, UseScenaResponsiveReturns, UseScenaReturns, UseScenaVisibilityReturns, UseVideoControllerOptions, UseVideoControllerReturns };
+export type { ComponentAriaProps, ComponentClasses, ComponentRef, ComponentSnippet, ComponentSnippetReturn, ComponentStyles, ScenaApi, ScenaButtonComponentClasses, ScenaButtonComponentStyles, ScenaButtonElements, ScenaButtonEvents, ScenaButtonProps, ScenaButtonSnippets, ScenaCloseButtonComponentClasses, ScenaCloseButtonComponentHtml, ScenaCloseButtonComponentStyles, ScenaCloseButtonElements, ScenaCloseButtonProps, ScenaCloseButtonRef, ScenaComponents, ScenaConfig, ScenaConfigFeatures, ScenaConfigOverrides, ScenaContainerCustomClasses, ScenaContainerCustomStyles, ScenaContainerElements, ScenaContainerProps, ScenaContainerRef, ScenaContainerSnippets, ScenaContext, ScenaCtaButtonAdaptive, ScenaCtaButtonComponentClasses, ScenaCtaButtonComponentHtml, ScenaCtaButtonComponentStyles, ScenaCtaButtonElements, ScenaCtaButtonProps, ScenaCtaButtonRef, ScenaElementTag, ScenaEventEmitter, ScenaEventHandler, ScenaEventMap, ScenaFeatures, ScenaIconCustomClasses, ScenaIconCustomStyles, ScenaIconElements, ScenaIconProps, ScenaIconSnippets, ScenaInstance, ScenaLoaderCustomClasses, ScenaLoaderCustomStyles, ScenaLoaderElements, ScenaLoaderProps, ScenaOverrides, ScenaPreviewApi, ScenaPreviewConfig, ScenaProgressCircleComponentClasses, ScenaProgressCircleComponentStyles, ScenaProgressCircleElements, ScenaProgressCircleEvents, ScenaProgressCircleProps, ScenaProgressComponentThickness, ScenaProgressLineComponentClasses, ScenaProgressLineComponentStyles, ScenaProgressLineElements, ScenaProgressLineEvents, ScenaProgressLineProps, ScenaProgressThickness, ScenaProps, ScenaRef, ScenaResponsiveApi, ScenaResponsiveConfig, ScenaTarget, ScenaVideoCallbacks, ScenaVideoComponentClasses, ScenaVideoComponentStyles, ScenaVideoContainerCustomClasses, ScenaVideoContainerCustomStyles, ScenaVideoContainerElements, ScenaVideoContainerProps, ScenaVideoContainerRef, ScenaVideoContainerSnippets, ScenaVideoContext, ScenaVideoControlsComponentAria, ScenaVideoControlsComponentClasses, ScenaVideoControlsComponentHtml, ScenaVideoControlsComponentStyles, ScenaVideoControlsElements, ScenaVideoControlsProps, ScenaVideoControlsRef, ScenaVideoData, ScenaVideoElements, ScenaVideoEventOptions, ScenaVideoEventOptionsWithError, ScenaVideoEventOptionsWithEvent, ScenaVideoLoaderComponentClasses, ScenaVideoLoaderComponentHtml, ScenaVideoLoaderComponentStyles, ScenaVideoLoaderElements, ScenaVideoLoaderProps, ScenaVideoLoaderRef, ScenaVideoMethods, ScenaVideoProgressComponentClasses, ScenaVideoProgressComponentStyles, ScenaVideoProgressComponentThickness, ScenaVideoProgressElements, ScenaVideoProgressProps, ScenaVideoProgressRef, ScenaVideoProgressThickness, ScenaVideoProgressThicknessMap, ScenaVideoProps, ScenaVideoRef, ScenaVideoSnippets, ScenaVideoVolumeComponentAria, ScenaVideoVolumeComponentClasses, ScenaVideoVolumeComponentHtml, ScenaVideoVolumeComponentStyles, ScenaVideoVolumeElements, ScenaVideoVolumeProps, ScenaVideoVolumeRef, ScenaVisibilityApi, ScenaVisibilityConfig, UseProgressCircleEvents, UseProgressCircleProps, UseProgressCircleReturn, UseProgressCircleReturnEvents, UseProgressLineEvents, UseProgressLineProps, UseProgressLineReturn, UseProgressLineReturnEvents, UseScenaConfigReturns, UseScenaOverridesReturns, UseScenaPreviewOptions, UseScenaPreviewReturns, UseScenaResponsiveReturns, UseScenaReturns, UseScenaVisibilityReturns, UseVideoControllerOptions, UseVideoControllerReturns };