@smartimpact-it/modern-video-embed 2.0.1

package/src/types/common.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Common Types for Video Embed Components
+ */
+
+/**
+ * Player state information
+ */
+export interface PlayerState {
+  playing: boolean;
+  muted: boolean;
+  videoId: string;
+  ready: boolean;
+  initialized: boolean;
+}
+
+/**
+ * YouTube Player Parameters
+ * @see https://developers.google.com/youtube/player_parameters
+ */
+export interface YouTubePlayerVars {
+  /** Whether to autoplay the video */
+  autoplay?: 0 | 1;
+  /** Whether to show video annotations */
+  iv_load_policy?: 1 | 3;
+  /** Start time in seconds */
+  start?: number;
+  /** End time in seconds */
+  end?: number;
+  /** Whether to show related videos */
+  rel?: 0 | 1;
+  /** Whether to show controls */
+  controls?: 0 | 1;
+  /** Whether to show YouTube logo */
+  modestbranding?: 0 | 1;
+  /** Whether to loop the video (requires playlist param) */
+  loop?: 0 | 1;
+  /** Playlist ID for looping */
+  playlist?: string;
+  /** Playback quality */
+  quality?:
+    | "small"
+    | "medium"
+    | "large"
+    | "hd720"
+    | "hd1080"
+    | "highres"
+    | "default";
+  /** Player color */
+  color?: "red" | "white";
+  /** Closed captions */
+  cc_load_policy?: 0 | 1;
+  /** Closed captions language */
+  cc_lang_pref?: string;
+  /** Disable keyboard controls */
+  disablekb?: 0 | 1;
+  /** Enable JavaScript API */
+  enablejsapi?: 0 | 1;
+  /** Fullscreen button */
+  fs?: 0 | 1;
+  /** Player language */
+  hl?: string;
+  /** Origin parameter for security */
+  origin?: string;
+  /** Widget referrer */
+  widget_referrer?: string;
+  /** Additional parameters */
+  [key: string]: string | number | undefined;
+}
+
+/**
+ * Vimeo Player Parameters
+ * @see https://developer.vimeo.com/player/sdk/embed
+ */
+export interface VimeoPlayerVars {
+  /** Whether to loop the video */
+  loop?: boolean;
+  /** Custom player color (hex without #) */
+  color?: string;
+  /** Show video title */
+  title?: boolean;
+  /** Show video author */
+  byline?: boolean;
+  /** Show author portrait */
+  portrait?: boolean;
+  /** Do Not Track */
+  dnt?: boolean;
+  /** Playback quality */
+  quality?: "360p" | "540p" | "720p" | "1080p" | "2k" | "4k" | "auto";
+  /** Muted */
+  muted?: boolean;
+  /** Background mode */
+  background?: boolean;
+  /** Transparent background */
+  transparent?: boolean;
+  /** Speed controls */
+  speed?: boolean;
+  /** Keyboard shortcuts */
+  keyboard?: boolean;
+  /** Picture in Picture */
+  pip?: boolean;
+  /** Playsinline on mobile */
+  playsinline?: boolean;
+  /** Responsive embed */
+  responsive?: boolean;
+  /** Additional parameters */
+  [key: string]: string | number | boolean | undefined;
+}
+
+/**
+ * Custom event detail for video embed events
+ */
+export interface VideoEventDetail {
+  /** Video ID */
+  videoId?: string;
+  /** Current time in seconds */
+  currentTime?: number;
+  /** Video duration in seconds */
+  duration?: number;
+  /** Error message */
+  message?: string;
+  /** Error code */
+  code?: number | string;
+  /** Additional data */
+  [key: string]: any;
+}
+
+/**
+ * Video embed custom events
+ */
+export interface VideoEmbedEventMap {
+  ready: CustomEvent<VideoEventDetail>;
+  play: CustomEvent<VideoEventDetail>;
+  pause: CustomEvent<VideoEventDetail>;
+  ended: CustomEvent<VideoEventDetail>;
+  error: CustomEvent<VideoEventDetail>;
+  timeupdate: CustomEvent<VideoEventDetail>;
+  loadstart: CustomEvent<VideoEventDetail>;
+  bufferstart: CustomEvent<VideoEventDetail>;
+  bufferend: CustomEvent<VideoEventDetail>;
+  qualitychange: CustomEvent<QualityChangeDetail>;
+}
+
+/**
+ * Attribute change callback parameters
+ */
+export interface AttributeChangeParams {
+  name: string;
+  oldValue: string | null;
+  newValue: string | null;
+}
+
+/**
+ * Video quality options
+ */
+export type YouTubeQuality =
+  | "tiny" // 144p
+  | "small" // 240p
+  | "medium" // 360p
+  | "large" // 480p
+  | "hd720" // 720p
+  | "hd1080" // 1080p
+  | "hd1440" // 1440p
+  | "hd2160" // 2160p (4K)
+  | "highres" // Higher than 1080p
+  | "default" // Auto quality
+  | "auto"; // Auto quality
+
+export type VimeoQuality =
+  | "240p"
+  | "360p"
+  | "540p"
+  | "720p"
+  | "1080p"
+  | "2k" // 1440p
+  | "4k" // 2160p
+  | "auto";
+
+/**
+ * Quality change event detail
+ */
+export interface QualityChangeDetail {
+  /** Previous quality level */
+  oldQuality: string;
+  /** New quality level */
+  newQuality: string;
+  /** Available quality levels */
+  availableQualities?: string[];
+}
+
+/**
+ * Fullscreen API types
+ */
+export interface FullscreenAPI {
+  requestFullscreen(): Promise<void>;
+  exitFullscreen(): Promise<void>;
+  readonly fullscreenElement: Element | null;
+  readonly fullscreenEnabled: boolean;
+}

package/src/types/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Central export point for all type definitions
+ */
+
+export * from "./common";
+export type { YouTubeEmbedElement } from "./youtube-embed";
+export type { VimeoEmbedElement } from "./vimeo-embed";

package/src/types/vimeo-embed.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Vimeo Embed Component API Documentation
+ */
+
+import type {
+  PlayerState,
+  VimeoPlayerVars,
+  VideoEventDetail,
+  VimeoQuality,
+} from "./common";
+
+export interface VimeoEmbedElement extends HTMLElement {
+  // Properties
+  url: string;
+  videoId: string;
+  autoplay: boolean;
+  controls: boolean;
+  lazy: boolean;
+  muted: boolean;
+  poster: string;
+  playing: boolean;
+  background: boolean;
+  playerVars: VimeoPlayerVars;
+
+  // Methods
+  play(): Promise<void>;
+  pause(): void;
+  stopVideo(): void;
+  mute(): void;
+  unmute(): void;
+  togglePlay(): void;
+  toggleMute(): void;
+  loadVideo(videoIdOrUrl: string): void;
+  getPlayerState(): PlayerState;
+  isPlaying(): boolean;
+  isMuted(): Promise<boolean>;
+  getCurrentTime(): Promise<number>;
+}
+
+// Custom Events
+export interface VimeoEmbedEvents {
+  ready: CustomEvent<VideoEventDetail>;
+  play: CustomEvent<VideoEventDetail>;
+  pause: CustomEvent<VideoEventDetail>;
+  stop: CustomEvent<VideoEventDetail>;
+  ended: CustomEvent<VideoEventDetail>;
+  error: CustomEvent<VideoEventDetail>;
+  connected: CustomEvent<void>;
+  disconnected: CustomEvent<void>;
+  timeupdate: CustomEvent<VideoEventDetail>;
+}
+
+// Usage Examples:
+
+// HTML Usage:
+// <vimeo-embed
+//   url="https://vimeo.com/123456789"
+//   autoplay
+//   controls
+//   lazy
+//   muted
+//   poster="custom-thumbnail.jpg">
+// </vimeo-embed>
+
+// JavaScript Usage:
+// const embed = document.querySelector('vimeo-embed');
+// embed.url = 'https://vimeo.com/123456789';
+// embed.autoplay = true;
+// embed.play();
+
+// Event Listening:
+// embed.addEventListener('ready', () => console.log('Player ready'));
+// embed.addEventListener('play', () => console.log('Video started'));
+// embed.addEventListener('pause', () => console.log('Video paused'));
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "vimeo-embed": VimeoEmbedElement;
+  }
+}

package/src/types/youtube-embed.d.ts

@@ -0,0 +1,83 @@
+/**
+ * YouTube Embed Component API Documentation
+ */
+
+import type {
+  PlayerState,
+  YouTubePlayerVars,
+  VideoEventDetail,
+  YouTubeQuality,
+} from "./common";
+
+export interface YouTubeEmbedElement extends HTMLElement {
+  // Properties
+  url: string;
+  videoId: string;
+  autoplay: boolean;
+  controls: boolean;
+  lazy: boolean;
+  muted: boolean;
+  poster: string;
+  playing: boolean;
+  background: boolean;
+  playerVars: YouTubePlayerVars;
+
+  // Methods
+  play(): Promise<void>;
+  pause(): void;
+  stopVideo(): void;
+  mute(): void;
+  unmute(): void;
+  togglePlay(): void;
+  toggleMute(): void;
+  loadVideo(videoIdOrUrl: string): void;
+  getPlayerState(): PlayerState;
+  getCurrentTime(): number;
+  isPlaying(): boolean;
+  isMuted(): boolean;
+}
+
+// Custom Events
+export interface YouTubeEmbedEvents {
+  ready: CustomEvent<VideoEventDetail>;
+  play: CustomEvent<VideoEventDetail>;
+  pause: CustomEvent<VideoEventDetail>;
+  ended: CustomEvent<VideoEventDetail>;
+  error: CustomEvent<VideoEventDetail>;
+  timeupdate: CustomEvent<VideoEventDetail>;
+  stop: CustomEvent<VideoEventDetail>;
+  connected: CustomEvent<void>;
+  disconnected: CustomEvent<void>;
+}
+
+// Usage Examples:
+
+// HTML Usage:
+// <youtube-embed
+//   url="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+//   autoplay
+//   controls
+//   lazy
+//   muted
+//   poster="custom-thumbnail.jpg"
+//   player-vars='{"loop": 1, "quality": "hd720"}'>
+// </youtube-embed>
+
+// JavaScript Usage:
+// const embed = document.querySelector('youtube-embed');
+// embed.url = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ';
+// embed.autoplay = true;
+// embed.playerVars = { loop: 1, quality: 'hd720' };
+// embed.play();
+
+// Event Listening:
+// embed.addEventListener('ready', (e) => console.log('Player ready', e.detail));
+// embed.addEventListener('play', (e) => console.log('Video started', e.detail));
+// embed.addEventListener('pause', (e) => console.log('Video paused', e.detail));
+// embed.addEventListener('error', (e) => console.error('Error:', e.detail.message));
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "youtube-embed": YouTubeEmbedElement;
+  }
+}

package/src/vimeo-only.ts

@@ -0,0 +1,9 @@
+/**
+ * Vimeo-only bundle entry point
+ * Use this for smaller bundle size when only Vimeo embeds are needed
+ */
+
+export { VimeoEmbed } from "./components/VimeoEmbed";
+
+// Auto-register the custom element
+import "./components/VimeoEmbed";

package/src/youtube-only.ts

@@ -0,0 +1,9 @@
+/**
+ * YouTube-only bundle entry point
+ * Use this for smaller bundle size when only YouTube embeds are needed
+ */
+
+export { YouTubeEmbed } from "./components/YouTubeEmbed";
+
+// Auto-register the custom element
+import "./components/YouTubeEmbed";