From 415b5436e2dcce1f5b7559940e1d7e23301d1fba Mon Sep 17 00:00:00 2001
From: omsherikar <omsherikar0229@gmail.com>
Date: Fri, 24 Oct 2025 03:47:27 +0530
Subject: [PATCH 1/4] feat(videos): implement embedded video player with
 ultra-large modal

- Add beautiful video modal with YouTube/Vimeo embed support
- Implement ultra-large responsive modal (95vw width, 70-85vh height)
- Add smooth animations and loading states with gradient backgrounds
- Include full accessibility support with ARIA labels and focus management
- Use semantic HTML5 elements (dialog, header, section) for better structure
- Follow Tailwind CSS best practices with @layer components
- Add keyboard navigation and screen reader support
- Implement mobile-first responsive design with dark mode support
- Replace YouTube redirects with embedded video player
- Maintain CONTRIBUTING.md compliance throughout

Closes #620
---
 web/templates/videos/list.html | 284 +++++++++++++++++++++++++++++++--
 1 file changed, 273 insertions(+), 11 deletions(-)

diff --git a/web/templates/videos/list.html b/web/templates/videos/list.html
index 3be0307fa..71134931d 100644
--- a/web/templates/videos/list.html
+++ b/web/templates/videos/list.html
@@ -22,6 +22,125 @@
               transform: translateY(0);
           }
       }
+
+      /* Video Modal - Following Tailwind Best Practices */
+      @layer components {
+          .video-modal {
+              @apply hidden fixed inset-0 z-50 bg-black bg-opacity-90 backdrop-blur-sm opacity-0 transition-all duration-300 ease-out;
+          }
+
+          .video-modal.show {
+              @apply flex items-center justify-center opacity-100;
+          }
+
+          .video-modal-content {
+              @apply relative bg-gradient-to-br from-gray-900 via-gray-800 to-gray-900 dark:from-gray-800 dark:via-gray-700 dark:to-gray-800 rounded-3xl overflow-hidden max-w-[95vw] w-full mx-2 shadow-2xl border border-white border-opacity-20 transform scale-95 transition-all duration-300 ease-out;
+              box-shadow: 
+                  0 32px 64px -12px rgba(0, 0, 0, 0.6),
+                  0 0 0 1px rgba(255, 255, 255, 0.1),
+                  inset 0 1px 0 rgba(255, 255, 255, 0.1);
+          }
+
+          .video-modal.show .video-modal-content {
+              @apply scale-100;
+          }
+
+          .video-modal-header {
+              @apply flex justify-between items-center px-6 py-5 bg-gradient-to-r from-gray-800 via-gray-700 to-gray-800 dark:from-gray-700 dark:via-gray-600 dark:to-gray-700 border-b border-gray-600 relative;
+              background: linear-gradient(135deg, #1f2937, #374151, #1f2937);
+          }
+
+          .video-modal-header::after {
+              content: '';
+              @apply absolute bottom-0 left-0 right-0 h-px bg-gradient-to-r from-transparent via-white to-transparent opacity-30;
+          }
+
+          .video-modal-title {
+              @apply text-white text-xl font-bold m-0 tracking-tight;
+              text-shadow: 0 2px 4px rgba(0, 0, 0, 0.5);
+          }
+
+          .video-modal-close {
+              @apply bg-white bg-opacity-10 border border-white border-opacity-20 text-white text-xl cursor-pointer p-2 rounded-lg transition-all duration-200 ease-out w-10 h-10 flex items-center justify-center hover:bg-opacity-20 hover:border-opacity-30 hover:scale-105 active:scale-95 focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 focus:outline-none;
+          }
+
+          .video-modal-body {
+              @apply relative;
+          }
+
+          .video-modal-iframe {
+              @apply w-full h-[70vh] sm:h-[75vh] lg:h-[80vh] xl:h-[85vh] border-0 rounded-b-3xl;
+              background: linear-gradient(45deg, #1a1a1a, #2a2a2a);
+          }
+
+          .video-card {
+              @apply transition-all duration-300 ease-out relative overflow-hidden;
+          }
+
+          .video-card:hover {
+              @apply -translate-y-1 shadow-xl;
+          }
+
+          .video-card .video-link i.fa-play {
+              @apply transition-all duration-300 ease-out;
+          }
+
+          .video-card:hover .video-link i.fa-play {
+              @apply scale-110;
+          }
+
+          .sr-only {
+              @apply absolute w-px h-px p-0 -m-px overflow-hidden whitespace-nowrap border-0;
+              clip: rect(0, 0, 0, 0);
+          }
+      }
+
+      /* Enhanced Responsive Design - Mobile First */
+      @media (max-width: 768px) {
+          .video-modal-content {
+              @apply mx-1 rounded-2xl;
+              max-width: 98vw;
+          }
+          
+          .video-modal-iframe {
+              @apply h-[65vh];
+          }
+
+          .video-modal-header {
+              @apply px-4 py-4;
+          }
+
+          .video-modal-title {
+              @apply text-lg;
+          }
+
+          .video-modal-close {
+              @apply w-9 h-9 p-1.5;
+          }
+      }
+
+      @media (max-width: 480px) {
+          .video-modal-content {
+              @apply mx-0.5 rounded-xl;
+              max-width: 99vw;
+          }
+          
+          .video-modal-iframe {
+              @apply h-[60vh];
+          }
+
+          .video-modal-header {
+              @apply px-3 py-3;
+          }
+
+          .video-modal-title {
+              @apply text-base;
+          }
+
+          .video-modal-close {
+              @apply w-8 h-8 p-1;
+          }
+      }
   </style>
 {% endblock %}
 {% block content %}
@@ -93,24 +212,24 @@ <h1 class="text-2xl font-bold">
                 <!-- Video Preview -->
                 <div class="aspect-w-16 aspect-h-9 bg-gray-100 dark:bg-gray-700">
                   {% if video.thumbnail_url %}
-                    <div class="relative aspect-w-16 aspect-h-9 overflow-hidden rounded-lg shadow-sm">
+                    <div class="video-card relative aspect-w-16 aspect-h-9 overflow-hidden rounded-lg shadow-sm">
                       <img src="{{ video.thumbnail_url }}"
                            alt="{{ video.title }} thumbnail"
                            class="w-full h-full object-cover" />
-                      <a href="{{ video.video_url }}"
-                         target="_blank"
-                         class="absolute inset-0 flex items-center justify-center bg-black bg-opacity-25 hover:bg-opacity-0 transition-opacity">
+                      <a href="javascript:void(0)"
+                         onclick="openVideoModal('{{ video.video_url }}', '{{ video.title|escapejs }}')"
+                         class="video-link absolute inset-0 flex items-center justify-center bg-black bg-opacity-25 hover:bg-opacity-0 transition-opacity">
                         <i class="fas fa-play text-white text-4xl"></i>
                       </a>
                     </div>
                   {% elif video.thumbnail_url %}
-                    <div class="relative aspect-w-16 aspect-h-9 overflow-hidden rounded-lg shadow-sm">
+                    <div class="video-card relative aspect-w-16 aspect-h-9 overflow-hidden rounded-lg shadow-sm">
                       <img src="{{ video.thumbnail_url }}"
                            alt="{{ video.title }} thumbnail"
                            class="w-full h-full object-cover" />
-                      <a href="{{ video.video_url }}"
-                         target="_blank"
-                         class="absolute inset-0 flex items-center justify-center bg-black bg-opacity-25 hover:bg-opacity-0 transition-opacity">
+                      <a href="javascript:void(0)"
+                         onclick="openVideoModal('{{ video.video_url }}', '{{ video.title|escapejs }}')"
+                         class="video-link absolute inset-0 flex items-center justify-center bg-black bg-opacity-25 hover:bg-opacity-0 transition-opacity">
                         <i class="fas fa-play text-white text-4xl"></i>
                       </a>
                     </div>
@@ -123,9 +242,9 @@ <h1 class="text-2xl font-bold">
                 <!-- Video Info -->
                 <div class="p-4">
                   <h3 class="text-lg font-semibold mb-2 line-clamp-2">
-                    <a href="{{ video.video_url }}"
-                       target="_blank"
-                       class="hover:text-orange-500 transition-colors">{{ video.title }}</a>
+                    <a href="javascript:void(0)"
+                       onclick="openVideoModal('{{ video.video_url }}', '{{ video.title|escapejs }}')"
+                       class="video-link hover:text-orange-500 transition-colors cursor-pointer">{{ video.title }}</a>
                   </h3>
                   <div class="flex items-center text-sm text-gray-500 dark:text-gray-400 mb-2">
                     {% if video.uploader %}
@@ -304,4 +423,147 @@ <h2 class="text-lg font-semibold">Request an Educational Video</h2>
       </div>
     </div>
   </main>
+
+  <!-- Video Modal - Semantic HTML5 Structure -->
+  <dialog id="videoModal" class="video-modal" role="dialog" aria-labelledby="videoModalTitle" aria-modal="true">
+    <div class="video-modal-content">
+      <header class="video-modal-header">
+        <h2 id="videoModalTitle" class="video-modal-title"></h2>
+        <button id="videoModalClose" class="video-modal-close" aria-label="Close video player" type="button">
+          <span class="sr-only">Close</span>
+          <i class="fas fa-times" aria-hidden="true"></i>
+        </button>
+      </header>
+      <section class="video-modal-body">
+        <iframe id="videoModalIframe" 
+                class="video-modal-iframe" 
+                src="" 
+                title="Video player"
+                frameborder="0" 
+                allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" 
+                allowfullscreen>
+        </iframe>
+      </section>
+    </div>
+  </dialog>
+
+  <script>
+    // Get modal elements
+    const videoModal = document.getElementById('videoModal');
+    const videoModalTitle = document.getElementById('videoModalTitle');
+    const videoModalIframe = document.getElementById('videoModalIframe');
+    const videoModalClose = document.getElementById('videoModalClose');
+
+    // Function to extract YouTube video ID
+    function getYouTubeVideoId(url) {
+      const regExp = /^.*(youtu.be\/|v\/|u\/\w\/|embed\/|watch\?v=|&v=)([^#&?]*).*/;
+      const match = url.match(regExp);
+      return (match && match[2].length === 11) ? match[2] : null;
+    }
+
+    // Function to extract Vimeo video ID
+    function getVimeoVideoId(url) {
+      const regExp = /^.*(vimeo\.com\/)((channels\/[A-z]+\/)|(groups\/[A-z]+\/videos\/)|(videos\/)|)([0-9]+)/;
+      const match = url.match(regExp);
+      return match ? match[6] : null;
+    }
+
+    // Function to open video modal
+    function openVideoModal(videoUrl, videoTitle) {
+      let embedUrl = '';
+      const youtubeId = getYouTubeVideoId(videoUrl);
+      const vimeoId = getVimeoVideoId(videoUrl);
+
+      if (youtubeId) {
+        embedUrl = `https://www.youtube.com/embed/${youtubeId}?autoplay=1&rel=0&modestbranding=1&enablejsapi=1`;
+      } else if (vimeoId) {
+        embedUrl = `https://player.vimeo.com/video/${vimeoId}?autoplay=1&title=0&byline=0&portrait=0`;
+      } else {
+        // Fallback to original URL for unsupported platforms
+        window.open(videoUrl, '_blank');
+        return;
+      }
+
+      // Set title and accessibility attributes
+      videoModalTitle.textContent = videoTitle;
+      videoModalIframe.title = `Video player for ${videoTitle}`;
+      
+      // Show modal with smooth animation
+      videoModal.style.display = 'flex';
+      videoModal.style.opacity = '0';
+      videoModal.querySelector('.video-modal-content').style.transform = 'scale(0.9) translateY(20px)';
+      
+      // Trigger reflow and animate in
+      requestAnimationFrame(() => {
+        videoModal.classList.add('show');
+        videoModal.style.opacity = '1';
+        videoModal.querySelector('.video-modal-content').style.transform = 'scale(1) translateY(0)';
+        document.body.style.overflow = 'hidden';
+      });
+      
+      // Set iframe source
+      videoModalIframe.src = embedUrl;
+      
+      // Focus management for accessibility
+      videoModalClose.focus();
+    }
+
+    // Function to close video modal
+    function closeVideoModal() {
+      // Animate out with smooth transition
+      videoModal.style.opacity = '0';
+      videoModal.querySelector('.video-modal-content').style.transform = 'scale(0.9) translateY(20px)';
+      
+      setTimeout(() => {
+        // Close modal with proper accessibility
+        videoModal.classList.remove('show');
+        videoModal.style.display = 'none';
+        videoModalIframe.src = '';
+        document.body.style.overflow = '';
+        
+        // Return focus to the video link that opened the modal
+        if (document.activeElement && document.activeElement.classList.contains('video-link')) {
+          document.activeElement.focus();
+        }
+      }, 300);
+    }
+
+    // Event listeners
+    videoModalClose.addEventListener('click', closeVideoModal);
+
+    // Close modal when clicking outside
+    videoModal.addEventListener('click', function(e) {
+      if (e.target === videoModal) {
+        closeVideoModal();
+      }
+    });
+
+    // Keyboard navigation
+    document.addEventListener('keydown', function(e) {
+      if (videoModal.classList.contains('show')) {
+        if (e.key === 'Escape') {
+          closeVideoModal();
+        }
+        
+        // Tab trapping for accessibility
+        if (e.key === 'Tab') {
+          const focusableElements = videoModal.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
+          const firstElement = focusableElements[0];
+          const lastElement = focusableElements[focusableElements.length - 1];
+          
+          if (e.shiftKey) {
+            if (document.activeElement === firstElement) {
+              lastElement.focus();
+              e.preventDefault();
+            }
+          } else {
+            if (document.activeElement === lastElement) {
+              firstElement.focus();
+              e.preventDefault();
+            }
+          }
+        }
+      }
+    });
+  </script>
 {% endblock %}

From ff36eaa86c19626296bc7c12e6fbe3a4551ec2b1 Mon Sep 17 00:00:00 2001
From: omsherikar <omsherikar0229@gmail.com>
Date: Fri, 24 Oct 2025 03:55:12 +0530
Subject: [PATCH 2/4] fix(videos): remove duplicate video thumbnail markup

- Remove redundant {% elif video.thumbnail_url %} block
- Fix copy-paste error that created identical conditional blocks
- Clean up template structure for better maintainability

The second condition was unreachable since the first already handled
the video.thumbnail_url case.
---
 web/templates/videos/list.html | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/web/templates/videos/list.html b/web/templates/videos/list.html
index 71134931d..fea37f562 100644
--- a/web/templates/videos/list.html
+++ b/web/templates/videos/list.html
@@ -222,17 +222,6 @@ <h1 class="text-2xl font-bold">
                         <i class="fas fa-play text-white text-4xl"></i>
                       </a>
                     </div>
-                  {% elif video.thumbnail_url %}
-                    <div class="video-card relative aspect-w-16 aspect-h-9 overflow-hidden rounded-lg shadow-sm">
-                      <img src="{{ video.thumbnail_url }}"
-                           alt="{{ video.title }} thumbnail"
-                           class="w-full h-full object-cover" />
-                      <a href="javascript:void(0)"
-                         onclick="openVideoModal('{{ video.video_url }}', '{{ video.title|escapejs }}')"
-                         class="video-link absolute inset-0 flex items-center justify-center bg-black bg-opacity-25 hover:bg-opacity-0 transition-opacity">
-                        <i class="fas fa-play text-white text-4xl"></i>
-                      </a>
-                    </div>
                   {% elif 'vimeo.com' in video.video_url %}
                     <!-- your existing Vimeo preview here -->
                   {% else %}

From ba3daaf90ccc0935c4bdfdc37c5e212fc4e67bac Mon Sep 17 00:00:00 2001
From: omsherikar <omsherikar0229@gmail.com>
Date: Fri, 24 Oct 2025 03:59:12 +0530
Subject: [PATCH 3/4] fix(accessibility): improve focus restoration in video
 modal

- Store reference to triggering element for reliable focus restoration
- Pass event object to openVideoModal function to capture caller
- Replace unreliable focus detection with explicit element reference
- Add proper cleanup of triggering element reference
- Ensure focus returns to the exact element that opened the modal
- Improve screen reader experience and keyboard navigation

Fixes focus restoration issues where focus could shift during modal
interaction, making the close button the active element instead of
the original triggering link.
---
 web/templates/videos/list.html | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/web/templates/videos/list.html b/web/templates/videos/list.html
index fea37f562..7cfec38bb 100644
--- a/web/templates/videos/list.html
+++ b/web/templates/videos/list.html
@@ -217,7 +217,7 @@ <h1 class="text-2xl font-bold">
                            alt="{{ video.title }} thumbnail"
                            class="w-full h-full object-cover" />
                       <a href="javascript:void(0)"
-                         onclick="openVideoModal('{{ video.video_url }}', '{{ video.title|escapejs }}')"
+                         onclick="openVideoModal('{{ video.video_url }}', '{{ video.title|escapejs }}', event)"
                          class="video-link absolute inset-0 flex items-center justify-center bg-black bg-opacity-25 hover:bg-opacity-0 transition-opacity">
                         <i class="fas fa-play text-white text-4xl"></i>
                       </a>
@@ -232,7 +232,7 @@ <h1 class="text-2xl font-bold">
                 <div class="p-4">
                   <h3 class="text-lg font-semibold mb-2 line-clamp-2">
                     <a href="javascript:void(0)"
-                       onclick="openVideoModal('{{ video.video_url }}', '{{ video.title|escapejs }}')"
+                       onclick="openVideoModal('{{ video.video_url }}', '{{ video.title|escapejs }}', event)"
                        class="video-link hover:text-orange-500 transition-colors cursor-pointer">{{ video.title }}</a>
                   </h3>
                   <div class="flex items-center text-sm text-gray-500 dark:text-gray-400 mb-2">
@@ -443,6 +443,9 @@ <h2 id="videoModalTitle" class="video-modal-title"></h2>
     const videoModalIframe = document.getElementById('videoModalIframe');
     const videoModalClose = document.getElementById('videoModalClose');
 
+    // Store reference to the element that opened the modal for proper focus restoration
+    let triggeringElement = null;
+
     // Function to extract YouTube video ID
     function getYouTubeVideoId(url) {
       const regExp = /^.*(youtu.be\/|v\/|u\/\w\/|embed\/|watch\?v=|&v=)([^#&?]*).*/;
@@ -458,7 +461,10 @@ <h2 id="videoModalTitle" class="video-modal-title"></h2>
     }
 
     // Function to open video modal
-    function openVideoModal(videoUrl, videoTitle) {
+    function openVideoModal(videoUrl, videoTitle, event) {
+      // Capture the element that triggered the modal for proper focus restoration
+      triggeringElement = event?.target || document.activeElement;
+      
       let embedUrl = '';
       const youtubeId = getYouTubeVideoId(videoUrl);
       const vimeoId = getVimeoVideoId(videoUrl);
@@ -510,10 +516,13 @@ <h2 id="videoModalTitle" class="video-modal-title"></h2>
         videoModalIframe.src = '';
         document.body.style.overflow = '';
         
-        // Return focus to the video link that opened the modal
-        if (document.activeElement && document.activeElement.classList.contains('video-link')) {
-          document.activeElement.focus();
+        // Restore focus to the element that opened the modal
+        if (triggeringElement && document.contains(triggeringElement)) {
+          triggeringElement.focus();
         }
+        
+        // Clear the reference
+        triggeringElement = null;
       }, 300);
     }
 

From 079128eebd854d5eec51eec7744e82b7bfe5b842 Mon Sep 17 00:00:00 2001
From: omsherikar <omsherikar0229@gmail.com>
Date: Fri, 24 Oct 2025 04:01:51 +0530
Subject: [PATCH 4/4] fix(accessibility): improve tab trapping and keyboard
 navigation

- Enhance tab trapping logic to handle edge cases properly
- Add disabled element filtering to focusable elements selector
- Handle case where no focusable elements exist (prevent tab escape)
- Improve focus order by focusing title first for screen readers
- Add tabindex to modal title for better keyboard accessibility
- Ensure robust tab cycling between first and last elements
- Fix potential issues with iframe focusability

The improved implementation now properly handles:
- Disabled form elements (excluded from tab order)
- Empty focusable elements list (prevents tab escape)
- Better focus order (title -> close button)
- More robust element selection criteria
---
 web/templates/videos/list.html | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/web/templates/videos/list.html b/web/templates/videos/list.html
index 7cfec38bb..9351fd8d6 100644
--- a/web/templates/videos/list.html
+++ b/web/templates/videos/list.html
@@ -417,7 +417,7 @@ <h2 class="text-lg font-semibold">Request an Educational Video</h2>
   <dialog id="videoModal" class="video-modal" role="dialog" aria-labelledby="videoModalTitle" aria-modal="true">
     <div class="video-modal-content">
       <header class="video-modal-header">
-        <h2 id="videoModalTitle" class="video-modal-title"></h2>
+        <h2 id="videoModalTitle" class="video-modal-title" tabindex="0"></h2>
         <button id="videoModalClose" class="video-modal-close" aria-label="Close video player" type="button">
           <span class="sr-only">Close</span>
           <i class="fas fa-times" aria-hidden="true"></i>
@@ -499,8 +499,8 @@ <h2 id="videoModalTitle" class="video-modal-title"></h2>
       // Set iframe source
       videoModalIframe.src = embedUrl;
       
-      // Focus management for accessibility
-      videoModalClose.focus();
+      // Focus management for accessibility - focus title first for screen readers
+      videoModalTitle.focus();
     }
 
     // Function to close video modal
@@ -541,21 +541,32 @@ <h2 id="videoModalTitle" class="video-modal-title"></h2>
       if (videoModal.classList.contains('show')) {
         if (e.key === 'Escape') {
           closeVideoModal();
+          return;
         }
-        
+
         // Tab trapping for accessibility
         if (e.key === 'Tab') {
-          const focusableElements = videoModal.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
+          const focusableElements = videoModal.querySelectorAll(
+            'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+          );
+          
+          if (focusableElements.length === 0) {
+            // No focusable elements; prevent tab escape
+            e.preventDefault();
+            return;
+          }
+          
           const firstElement = focusableElements[0];
           const lastElement = focusableElements[focusableElements.length - 1];
-          
+          const activeEl = document.activeElement;
+
           if (e.shiftKey) {
-            if (document.activeElement === firstElement) {
+            if (activeEl === firstElement) {
               lastElement.focus();
               e.preventDefault();
             }
           } else {
-            if (document.activeElement === lastElement) {
+            if (activeEl === lastElement) {
               firstElement.focus();
               e.preventDefault();
             }