From ba4bd31e4cb258be42000e8658e347d29811df84 Mon Sep 17 00:00:00 2001
From: totesforlife <toteally.notifications@gmail.com>
Date: Wed, 1 Oct 2025 19:18:00 -0700
Subject: [PATCH] Improve Custom Event types

---
 astro-cloudinary/index.ts                     |  1 +
 .../src/components/CldImage.astro             |  5 +-
 .../src/components/CldUploadWidget.astro      |  5 +-
 .../src/components/CldVideoPlayer.astro       |  3 +-
 astro-cloudinary/src/types/events.ts          | 69 +++++++++++++++++++
 docs/src/components/DemoImageEvents.astro     |  6 +-
 .../components/DemoUploadWidgetUnsigned.astro | 12 ++--
 .../components/DemoVideoPlayerEvents.astro    | 14 ++--
 .../src/content/docs/cldimage/basic-usage.mdx |  6 +-
 .../docs/clduploadwidget/basic-usage.mdx      |  8 ++-
 .../docs/clduploadwidget/configuration.mdx    |  6 +-
 .../docs/cldvideoplayer/basic-usage.mdx       | 16 +++--
 .../docs/cldvideoplayer/configuration.mdx     |  6 +-
 .../content/docs/cldvideoplayer/examples.mdx  | 14 ++--
 14 files changed, 130 insertions(+), 41 deletions(-)
 create mode 100644 astro-cloudinary/src/types/events.ts

diff --git a/astro-cloudinary/index.ts b/astro-cloudinary/index.ts
index 19fdc86..0fad1b8 100644
--- a/astro-cloudinary/index.ts
+++ b/astro-cloudinary/index.ts
@@ -1,4 +1,5 @@
 export * from './src/components/index.js';
+export * from './src/types/events.js';
 // export * from './helpers.js';
 
 // export { default as CldOgImage } from './components/CldOgImage';
diff --git a/astro-cloudinary/src/components/CldImage.astro b/astro-cloudinary/src/components/CldImage.astro
index b9969ba..df05a98 100644
--- a/astro-cloudinary/src/components/CldImage.astro
+++ b/astro-cloudinary/src/components/CldImage.astro
@@ -91,6 +91,7 @@ if (className) {
 
 <script>
   import { pollForProcessingImage } from '@cloudinary-util/util';
+  import type { CldImageErrorEventDetail } from '../types/events';
 
   document.addEventListener('error', onCldImageError, true);
     
@@ -100,10 +101,10 @@ if (className) {
     
     if ( !image || image.tagName !== 'IMG' ) return;
 
-    const customEvent = new CustomEvent('cldimage:error', {
+    const customEvent = new CustomEvent<CldImageErrorEventDetail>('cldimage:error', {
       detail: {
         Image: image,
-        type: 'error',
+        error: event,
       },
     });
 
diff --git a/astro-cloudinary/src/components/CldUploadWidget.astro b/astro-cloudinary/src/components/CldUploadWidget.astro
index 113385a..a8d6402 100644
--- a/astro-cloudinary/src/components/CldUploadWidget.astro
+++ b/astro-cloudinary/src/components/CldUploadWidget.astro
@@ -46,6 +46,7 @@ if ( typeof className === 'string' ) {
 
 <script>
 import type { CloudinaryCreateUploadWidget, CloudinaryUploadWidget } from '@cloudinary-util/types';
+import type { CldUploadWidgetEventDetail, CldUploadWidgetErrorEventDetail } from '../types/events';
 import { generateSignatureCallback, generateUploadWidgetResultCallback } from "@cloudinary-util/url-loader";
 import { triggerOnIdle, loadScript } from '../lib/util';
 
@@ -111,7 +112,7 @@ window.addEventListener('load', async () => {
 
     const resultsCallback = generateUploadWidgetResultCallback({
       onError: (uploadError) => {
-        const customEvent = new CustomEvent(`clduploadwidget:error`, {
+        const customEvent = new CustomEvent<CldUploadWidgetErrorEventDetail>(`clduploadwidget:error`, {
           detail: {
             event: 'error',
             error: uploadError,
@@ -124,7 +125,7 @@ window.addEventListener('load', async () => {
       onResult: (uploadResult) => {
         if ( typeof uploadResult?.event !== 'string' ) return;
 
-        const customEvent = new CustomEvent(`clduploadwidget:${uploadResult?.event}`, {
+        const customEvent = new CustomEvent<CldUploadWidgetEventDetail>(`clduploadwidget:${uploadResult?.event}`, {
           detail: {
             event: uploadResult.event,
             info: uploadResult.info,
diff --git a/astro-cloudinary/src/components/CldVideoPlayer.astro b/astro-cloudinary/src/components/CldVideoPlayer.astro
index 4ad8ab0..b7c5780 100644
--- a/astro-cloudinary/src/components/CldVideoPlayer.astro
+++ b/astro-cloudinary/src/components/CldVideoPlayer.astro
@@ -75,6 +75,7 @@ if ( className ) {
 
 <script>
 import type { CloudinaryVideoPlayer } from '@cloudinary-util/types';
+import type { CldVideoPlayerEventDetail } from '../types/events';
 import { loadScript } from '../lib/util';
 
 interface Cloudinary {
@@ -158,7 +159,7 @@ window.addEventListener('load', async () => {
 
     events.forEach(event => {
       player.on(event, (e: { Player: CloudinaryVideoPlayer; type: string; }) => {
-        const customEvent = new CustomEvent(`cldvideoplayer:${event}`, {
+        const customEvent = new CustomEvent<CldVideoPlayerEventDetail>(`cldvideoplayer:${event}`, {
           detail: {
             Player: e.Player,
             type: e.type,
diff --git a/astro-cloudinary/src/types/events.ts b/astro-cloudinary/src/types/events.ts
new file mode 100644
index 0000000..3d9a5d0
--- /dev/null
+++ b/astro-cloudinary/src/types/events.ts
@@ -0,0 +1,69 @@
+// CldVideoPlayer event details
+export interface CldVideoPlayerEventDetail {
+  Player: any;
+  type: string;
+  Video: HTMLVideoElement;
+}
+
+// CldUploadWidget event details
+export interface CldUploadWidgetEventDetail {
+  event: string;
+  info?: any;
+  UploadWidget: any;
+}
+
+export interface CldUploadWidgetErrorEventDetail {
+  event: 'error';
+  error: any;
+  UploadWidget: HTMLSpanElement;
+}
+
+// CldImage event details
+export interface CldImageErrorEventDetail {
+  error: Event | string;
+  Image: HTMLImageElement;
+}
+
+// Declare custom events for better type safety
+declare global {
+  interface WindowEventMap {
+    'cldvideoplayer:loadstart': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:suspend': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:abort': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:error': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:emptied': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:stalled': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:loadedmetadata': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:loadeddata': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:canplay': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:canplaythrough': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:playing': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:waiting': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:seeking': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:seeked': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:ended': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:durationchange': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:timeupdate': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:progress': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:play': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:pause': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:ratechange': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:volumechange': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:fullscreenchange': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:posterchange': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:mute': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:unmute': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:percentsplayed': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:timeplayed': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:seek': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:sourcechanged': CustomEvent<CldVideoPlayerEventDetail>;
+    'cldvideoplayer:qualitychanged': CustomEvent<CldVideoPlayerEventDetail>;
+  }
+  
+  interface HTMLElementEventMap {
+    'clduploadwidget:error': CustomEvent<CldUploadWidgetErrorEventDetail>;
+    'clduploadwidget:success': CustomEvent<CldUploadWidgetEventDetail>;
+    'clduploadwidget:queues-end': CustomEvent<CldUploadWidgetEventDetail>;
+    'cldimage:error': CustomEvent<CldImageErrorEventDetail>;
+  }
+} 
\ No newline at end of file
diff --git a/docs/src/components/DemoImageEvents.astro b/docs/src/components/DemoImageEvents.astro
index 221daa8..14487cc 100644
--- a/docs/src/components/DemoImageEvents.astro
+++ b/docs/src/components/DemoImageEvents.astro
@@ -8,11 +8,13 @@ const props: Props = Astro.props;
 <CldImage {...props} id="cldimage-event-demo" />
 
 <script>
+import type { CldImageErrorEventDetail } from '../../../astro-cloudinary';
+
 const image = document.querySelector('#cldimage-event-demo');
 
 if ( image ) {
-  image.addEventListener('cldimage:error', ((e: CustomEvent<{ detail: {} }>) => {
+  image.addEventListener('cldimage:error', (e: CustomEvent<CldImageErrorEventDetail>) => {
     console.log('cldimage:error', e.detail)
-  }) as EventListener);
+  });
 };
 </script>
\ No newline at end of file
diff --git a/docs/src/components/DemoUploadWidgetUnsigned.astro b/docs/src/components/DemoUploadWidgetUnsigned.astro
index 19f7a16..13f5f3b 100644
--- a/docs/src/components/DemoUploadWidgetUnsigned.astro
+++ b/docs/src/components/DemoUploadWidgetUnsigned.astro
@@ -23,6 +23,8 @@ const props: Props = Astro.props;
 </HeaderImage>
 
 <script>
+import type { CldUploadWidgetEventDetail } from '../../../astro-cloudinary';
+
 const demos = Array.from(document.querySelectorAll('.clduploadwidget-demo'));
 
 demos.forEach(demo => {
@@ -32,26 +34,24 @@ demos.forEach(demo => {
 
   if ( !widget ) return;
 
-  widget.addEventListener('clduploadwidget:success', ((e: CustomEvent<{ detail: { info: { secure_url: string } } }>) => {
+  widget.addEventListener('clduploadwidget:success', (e: CustomEvent<CldUploadWidgetEventDetail>) => {
     console.log('clduploadwidget:success', e.detail)
 
     if ( !uploadResult || !template ) return;
 
     const result = template.content.cloneNode(true) as HTMLTemplateElement;
-    // @ts-expect-error
     result.querySelector('img')?.setAttribute('src', e.detail.info.secure_url);
     uploadResult.innerHTML = '';
     uploadResult.appendChild(result);
     uploadResult.classList.remove('hidden');
 
     demo?.setAttribute('data-has-results', 'true');
-  }) as EventListener);
+  });
 
-  widget.addEventListener('clduploadwidget:queues-end', ((e: CustomEvent<{ detail: { UploadWidget: any } }>) => {
+  widget.addEventListener('clduploadwidget:queues-end', (e: CustomEvent<CldUploadWidgetEventDetail>) => {
     console.log('clduploadwidget:onqueuesend', e.detail)
-    // @ts-expect-error
     e.detail.UploadWidget?.close();
-  }) as EventListener);
+  });
 
 })
 </script>
\ No newline at end of file
diff --git a/docs/src/components/DemoVideoPlayerEvents.astro b/docs/src/components/DemoVideoPlayerEvents.astro
index 16de40a..6db4d35 100644
--- a/docs/src/components/DemoVideoPlayerEvents.astro
+++ b/docs/src/components/DemoVideoPlayerEvents.astro
@@ -8,19 +8,21 @@ const props: Props = Astro.props;
 <CldVideoPlayer {...props} id="cldvideoplayer-event-demo" />
 
 <script>
+import type { CldVideoPlayerEventDetail } from '../../../astro-cloudinary';
+
 const videoPlayer = document.querySelector(`#cldvideoplayer-event-demo`);
 
 if ( videoPlayer ) {
-  videoPlayer.addEventListener('cldvideoplayer:loadedmetadata', ((e: CustomEvent<{ detail: {} }>) => {
+  videoPlayer.addEventListener('cldvideoplayer:loadedmetadata', (e: CustomEvent<CldVideoPlayerEventDetail>) => {
     console.log('cldvideoplayer:loadedmetadata', e.detail)
-  }) as EventListener);
+  });
 
-  videoPlayer.addEventListener('cldvideoplayer:play', ((e: CustomEvent<{ detail: {} }>) => {
+  videoPlayer.addEventListener('cldvideoplayer:play', (e: CustomEvent<CldVideoPlayerEventDetail>) => {
     console.log('cldvideoplayer:play', e.detail)
-  }) as EventListener);
+  });
 
-  videoPlayer.addEventListener('cldvideoplayer:pause', ((e: CustomEvent<{ detail: {} }>) => {
+  videoPlayer.addEventListener('cldvideoplayer:pause', (e: CustomEvent<CldVideoPlayerEventDetail>) => {
     console.log('cldvideoplayer:pause', e.detail)
-  }) as EventListener);
+  });
 };
 </script>
\ No newline at end of file
diff --git a/docs/src/content/docs/cldimage/basic-usage.mdx b/docs/src/content/docs/cldimage/basic-usage.mdx
index 19c6d06..c38d866 100644
--- a/docs/src/content/docs/cldimage/basic-usage.mdx
+++ b/docs/src/content/docs/cldimage/basic-usage.mdx
@@ -263,12 +263,14 @@ import { CldImage } from 'astro-cloudinary';
 />
 
 <script>
+import type { CldImageErrorEventDetail } from 'astro-cloudinary';
+
 const image = document.querySelector(`#image-events`);
 
 if ( image ) {
-  image.addEventListener('cldimage:error', ((e: CustomEvent<{ detail: {} }>) => {
+  image.addEventListener('cldimage:error', (e: CustomEvent<CldImageErrorEventDetail>) => {
     console.log('cldimage:error', e.detail)
-  }) as EventListener);
+  });
 };
 </script>
 ```
diff --git a/docs/src/content/docs/clduploadwidget/basic-usage.mdx b/docs/src/content/docs/clduploadwidget/basic-usage.mdx
index ffdbd36..01bf119 100644
--- a/docs/src/content/docs/clduploadwidget/basic-usage.mdx
+++ b/docs/src/content/docs/clduploadwidget/basic-usage.mdx
@@ -148,17 +148,19 @@ import { CldUploadWidget } from 'astro-cloudinary';
 />
 
 <script>
+import type { CldUploadWidgetEventDetail } from 'astro-cloudinary';
+
 const widget = document.querySelector('#upload-events');
 
 if ( widget ) {
-  widget.addEventListener('clduploadwidget:success', ((e: CustomEvent<{ detail: object }>) => {
+  widget.addEventListener('clduploadwidget:success', (e: CustomEvent<CldUploadWidgetEventDetail>) => {
     console.log('clduploadwidget:success', e.detail);
     // {
     //  event: '<Event>',
     //  info: '<Cloudinary Resource>',
     //  UploadWidget // Widget Instance,
     // }
-  }) as EventListener);
+  });
 }
 </script>
 ```
@@ -178,7 +180,7 @@ methods such as `open` and `close`.
 
 <CodeBlock alwaysExpanded>
 ```jsx
-widget.addEventListener('clduploadwidget:queues-end', ((e: CustomEvent<{ detail: { UploadWidget: object } }>) => {
+widget.addEventListener('clduploadwidget:queues-end', (e: CustomEvent<CldUploadWidgetEventDetail>) => {
   e.detail.UploadWidget.close();
 });
 ```
diff --git a/docs/src/content/docs/clduploadwidget/configuration.mdx b/docs/src/content/docs/clduploadwidget/configuration.mdx
index 1653fb0..4a09a63 100644
--- a/docs/src/content/docs/clduploadwidget/configuration.mdx
+++ b/docs/src/content/docs/clduploadwidget/configuration.mdx
@@ -88,12 +88,14 @@ import { CldUploadWidget } from 'astro-cloudinary';
 />
 
 <script>
+import type { CldUploadWidgetEventDetail } from 'astro-cloudinary';
+
 const widget = document.querySelector('#upload-events');
 
 if ( widget ) {
-  widget.addEventListener('clduploadwidget:success', ((e: CustomEvent<{ detail: object }>) => {
+  widget.addEventListener('clduploadwidget:success', (e: CustomEvent<CldUploadWidgetEventDetail>) => {
     console.log('clduploadwidget:success', e.detail);
-  }) as EventListener);
+  });
 }
 </script>
 ```
diff --git a/docs/src/content/docs/cldvideoplayer/basic-usage.mdx b/docs/src/content/docs/cldvideoplayer/basic-usage.mdx
index 4b9189a..ccd77b8 100644
--- a/docs/src/content/docs/cldvideoplayer/basic-usage.mdx
+++ b/docs/src/content/docs/cldvideoplayer/basic-usage.mdx
@@ -94,7 +94,7 @@ For listening to player events for advanced interactions with:
 <CodeBlock>
 ```jsx
 ---
-import { CldVideoPlayer } from 'astro-cloudinary';
+import { CldVideoPlayer, type CldVideoPlayerEventDetail } from 'astro-cloudinary';
 ---
 <CldVideoPlayer
   id="video-player-events"
@@ -104,20 +104,22 @@ import { CldVideoPlayer } from 'astro-cloudinary';
 />
 
 <script>
+import type { CldVideoPlayerEventDetail } from 'astro-cloudinary';
+
 const videoPlayer = document.querySelector(`#video-player-events`);
 
 if ( videoPlayer ) {
-  videoPlayer.addEventListener('cldvideoplayer:loadedmetadata', ((e: CustomEvent<{ detail: {} }>) => {
+  videoPlayer.addEventListener('cldvideoplayer:loadedmetadata', (e: CustomEvent<CldVideoPlayerEventDetail>) => {
     console.log('cldvideoplayer:loadedmetadata', e.detail)
-  }) as EventListener);
+  });
 
-  videoPlayer.addEventListener('cldvideoplayer:play', ((e: CustomEvent<{ detail: {} }>) => {
+  videoPlayer.addEventListener('cldvideoplayer:play', (e: CustomEvent<CldVideoPlayerEventDetail>) => {
     console.log('cldvideoplayer:play', e.detail)
-  }) as EventListener);
+  });
 
-  videoPlayer.addEventListener('cldvideoplayer:pause', ((e: CustomEvent<{ detail: {} }>) => {
+  videoPlayer.addEventListener('cldvideoplayer:pause', (e: CustomEvent<CldVideoPlayerEventDetail>) => {
     console.log('cldvideoplayer:pause', e.detail)
-  }) as EventListener);
+  });
 };
 </script>
 ```
diff --git a/docs/src/content/docs/cldvideoplayer/configuration.mdx b/docs/src/content/docs/cldvideoplayer/configuration.mdx
index edcddfe..8478dc1 100644
--- a/docs/src/content/docs/cldvideoplayer/configuration.mdx
+++ b/docs/src/content/docs/cldvideoplayer/configuration.mdx
@@ -632,12 +632,14 @@ The events are triggered as global custom events which you can assign an event l
 <CldVideoPlayer {...props} id="video-player-events" />
 
 <script>
+import type { CldVideoPlayerEventDetail } from 'astro-cloudinary';
+
 const videoPlayer = document.querySelector(`#video-player-events`);
 
 if ( videoPlayer ) {
-  videoPlayer.addEventListener('cldvideoplayer:loadedmetadata', ((e: CustomEvent<{ detail: {} }>) => {
+  videoPlayer.addEventListener('cldvideoplayer:loadedmetadata', (e: CustomEvent<CldVideoPlayerEventDetail>) => {
     console.log('cldvideoplayer:loadedmetadata', e.detail)
-  }) as EventListener);
+  });
 }
 </script>
 ```
diff --git a/docs/src/content/docs/cldvideoplayer/examples.mdx b/docs/src/content/docs/cldvideoplayer/examples.mdx
index 6fe0190..7ba77e4 100644
--- a/docs/src/content/docs/cldvideoplayer/examples.mdx
+++ b/docs/src/content/docs/cldvideoplayer/examples.mdx
@@ -486,20 +486,22 @@ import { CldVideoPlayer } from 'astro-cloudinary';
 />
 
 <script>
+import type { CldVideoPlayerEventDetail } from 'astro-cloudinary';
+
 const videoPlayer = document.querySelector(`#video-player-events`);
 
 if ( videoPlayer ) {
-  videoPlayer.addEventListener('cldvideoplayer:loadedmetadata', ((e: CustomEvent<{ detail: {} }>) => {
+  videoPlayer.addEventListener('cldvideoplayer:loadedmetadata', (e: CustomEvent<CldVideoPlayerEventDetail>) => {
     console.log('cldvideoplayer:loadedmetadata', e.detail)
-  }) as EventListener);
+  });
 
-  videoPlayer.addEventListener('cldvideoplayer:play', ((e: CustomEvent<{ detail: {} }>) => {
+  videoPlayer.addEventListener('cldvideoplayer:play', (e: CustomEvent<CldVideoPlayerEventDetail>) => {
     console.log('cldvideoplayer:play', e.detail)
-  }) as EventListener);
+  });
 
-  videoPlayer.addEventListener('cldvideoplayer:pause', ((e: CustomEvent<{ detail: {} }>) => {
+  videoPlayer.addEventListener('cldvideoplayer:pause', (e: CustomEvent<CldVideoPlayerEventDetail>) => {
     console.log('cldvideoplayer:pause', e.detail)
-  }) as EventListener);
+  });
 };
 </script>
 ```