From e20ca52c307faf137c1a28dd7dac7bb9e9d8fc61 Mon Sep 17 00:00:00 2001
From: Omitogun Ayobami <omitogunr6@gmail.com>
Date: Thu, 20 Aug 2026 16:21:14 +0100
Subject: [PATCH] fix(a11y): trap dialog focus and restore opener

---
 src/app/components/accessibility/README.md |  10 +-
 src/components/CommandPalette.tsx          |  40 +++++-
 src/components/ConflictResolver.tsx        |  22 +++-
 src/components/CookieConsentBanner.tsx     |  66 +---------
 src/components/courses/VideoPreview.tsx    |  36 +++++-
 src/components/editor/MediaEmbedder.tsx    | 135 ++++++++++++---------
 src/components/notificationcenter.tsx      |  76 +++++++++---
 src/components/ui/Modal.tsx                |  21 ++--
 src/components/ui/__tests__/Modal.test.tsx | 126 +++----------------
 src/hooks/__tests__/useFocusTrap.test.tsx  |  51 ++++++++
 src/hooks/useAccessibility.tsx             |  43 +------
 src/hooks/useFocusTrap.ts                  |  94 ++++++++++++++
 12 files changed, 403 insertions(+), 317 deletions(-)
 create mode 100644 src/hooks/__tests__/useFocusTrap.test.tsx
 create mode 100644 src/hooks/useFocusTrap.ts

diff --git a/src/app/components/accessibility/README.md b/src/app/components/accessibility/README.md
index 6838498c..9864510b 100644
--- a/src/app/components/accessibility/README.md
+++ b/src/app/components/accessibility/README.md
@@ -145,12 +145,16 @@ return <div ref={containerRef}>{/* content */}</div>;
 
 ### useFocusTrap
 
-Traps focus within a container (for modals/dialogs).
+Traps focus within an active container, moves focus to an optional initial target,
+and restores focus to the opener when the dialog closes. New dialogs should import
+the shared hook directly.
 
 ```tsx
-import { useFocusTrap } from '@/hooks/useAccessibility';
+import { useRef } from 'react';
+import { useFocusTrap } from '@/hooks/useFocusTrap';
 
-const containerRef = useFocusTrap(isModalOpen);
+const initialFocusRef = useRef<HTMLInputElement>(null);
+const containerRef = useFocusTrap(isModalOpen, { initialFocusRef });
 return <div ref={containerRef}>{/* modal content */}</div>;
 ```
 
diff --git a/src/components/CommandPalette.tsx b/src/components/CommandPalette.tsx
index 05bc28cc..885d4ef7 100644
--- a/src/components/CommandPalette.tsx
+++ b/src/components/CommandPalette.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { useMemo, useState } from 'react';
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
 import { PollCreationModal, type PollDraft } from '@/components/polls/PollCreationModal';
 import { useSettingsStore } from '@/lib/settings/store';
 import { useToast } from '@/context/ToastContext';
@@ -12,6 +12,7 @@ import {
   useKeyboardShortcuts,
 } from '@/hooks/useKeyboardShortcuts';
 import { createLogger } from '@/lib/logging';
+import { useFocusTrap } from '@/hooks/useFocusTrap';
 const logger = createLogger('CommandPalette');
 
 function navigateTo(path: string): void {
@@ -92,6 +93,13 @@ export function CommandPalette() {
   const [query, setQuery] = useState('');
   const { theme, setTheme } = useTheme();
   const [pollModalOpen, setPollModalOpen] = useState(false);
+  const commandInputRef = useRef<HTMLInputElement>(null);
+  const commandPaletteRef = useFocusTrap<HTMLDivElement>(open && !showHelp, {
+    initialFocusRef: commandInputRef,
+  });
+  const shortcutHelpRef = useFocusTrap<HTMLDivElement>(showHelp);
+  const commandPaletteTitleId = useId();
+  const shortcutHelpTitleId = useId();
 
   const settings = useSettingsStore((s) => s.settings);
   const { info: toastInfo } = useToast();
@@ -179,6 +187,20 @@ export function CommandPalette() {
     );
   }, [commands, query]);
 
+  useEffect(() => {
+    if (!open && !showHelp) return;
+
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape') return;
+      event.preventDefault();
+      if (showHelp) setShowHelp(false);
+      else setOpen(false);
+    };
+
+    document.addEventListener('keydown', handleEscape);
+    return () => document.removeEventListener('keydown', handleEscape);
+  }, [open, showHelp]);
+
   return (
     <>
       {open ? (
@@ -189,12 +211,15 @@ export function CommandPalette() {
             aria-hidden="true"
           />
           <div
+            ref={commandPaletteRef}
             role="dialog"
             aria-modal="true"
-            aria-label="Command palette"
+            aria-labelledby={commandPaletteTitleId}
+            aria-hidden={showHelp || undefined}
             className="fixed left-1/2 top-20 z-[12001] w-[min(100vw-2rem,44rem)] -translate-x-1/2 rounded-xl border border-gray-200 bg-white p-3 shadow-xl dark:border-gray-700 dark:bg-gray-900"
           >
             <input
+              ref={commandInputRef}
               autoFocus
               value={query}
               onChange={(e) => setQuery(e.target.value)}
@@ -204,6 +229,9 @@ export function CommandPalette() {
               placeholder="Type a command..."
               className="w-full rounded-lg border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 dark:border-gray-700 dark:bg-gray-950 dark:text-gray-100"
             />
+            <h2 id={commandPaletteTitleId} className="sr-only">
+              Command palette
+            </h2>
 
             <div className="mt-3 max-h-80 overflow-auto rounded-lg border border-gray-200 dark:border-gray-700">
               {filtered.map((command) => {
@@ -258,13 +286,17 @@ export function CommandPalette() {
             aria-hidden="true"
           />
           <div
+            ref={shortcutHelpRef}
             role="dialog"
             aria-modal="true"
-            aria-label="Keyboard shortcuts help"
+            aria-labelledby={shortcutHelpTitleId}
             className="fixed left-1/2 top-1/2 z-[12011] max-h-[80vh] w-[min(100vw-2rem,54rem)] -translate-x-1/2 -translate-y-1/2 overflow-auto rounded-xl border border-gray-200 bg-white p-5 shadow-xl dark:border-gray-700 dark:bg-gray-900"
           >
             <div className="mb-4 flex items-center justify-between">
-              <h2 className="text-lg font-semibold text-gray-900 dark:text-gray-100">
+              <h2
+                id={shortcutHelpTitleId}
+                className="text-lg font-semibold text-gray-900 dark:text-gray-100"
+              >
                 Keyboard shortcuts
               </h2>
               <button
diff --git a/src/components/ConflictResolver.tsx b/src/components/ConflictResolver.tsx
index 222b5f00..65217962 100644
--- a/src/components/ConflictResolver.tsx
+++ b/src/components/ConflictResolver.tsx
@@ -1,9 +1,10 @@
 'use client';
 
-import React, { useState } from 'react';
+import React, { useEffect, useId, useState } from 'react';
 import { ConflictRecord, ResolutionStrategy } from '@/lib/conflict/types';
 import { motion, AnimatePresence } from 'framer-motion';
 import { X, AlertTriangle, ArrowRight, Save, History, Check } from 'lucide-react';
+import { useFocusTrap } from '@/hooks/useFocusTrap';
 
 interface ConflictResolverProps {
   conflict: ConflictRecord<any>;
@@ -18,6 +19,16 @@ export const ConflictResolver: React.FC<ConflictResolverProps> = ({
 }) => {
   const [selectedStrategy, setSelectedStrategy] = useState<ResolutionStrategy>('manual');
   const [showHistory, setShowHistory] = useState(false);
+  const dialogRef = useFocusTrap<HTMLDivElement>(true);
+  const titleId = useId();
+
+  useEffect(() => {
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') onClose();
+    };
+    document.addEventListener('keydown', handleEscape);
+    return () => document.removeEventListener('keydown', handleEscape);
+  }, [onClose]);
 
   const localItems = Object.entries(conflict.localData).filter(
     ([key]) => !['updatedAt', 'version', 'id'].includes(key),
@@ -31,6 +42,10 @@ export const ConflictResolver: React.FC<ConflictResolverProps> = ({
     <AnimatePresence>
       <div className="fixed inset-0 z-50 flex items-center justify-center p-4 bg-black/60 backdrop-blur-sm">
         <motion.div
+          ref={dialogRef}
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby={titleId}
           initial={{ opacity: 0, scale: 0.95, y: 20 }}
           animate={{ opacity: 1, scale: 1, y: 0 }}
           exit={{ opacity: 0, scale: 0.95, y: 20 }}
@@ -43,7 +58,9 @@ export const ConflictResolver: React.FC<ConflictResolverProps> = ({
                 <AlertTriangle size={24} />
               </div>
               <div>
-                <h3 className="text-xl font-bold text-white">Conflict Detected</h3>
+                <h3 id={titleId} className="text-xl font-bold text-white">
+                  Conflict Detected
+                </h3>
                 <p className="text-sm text-gray-400">
                   Resolution required for {conflict.entityType}
                 </p>
@@ -51,6 +68,7 @@ export const ConflictResolver: React.FC<ConflictResolverProps> = ({
             </div>
             <button
               onClick={onClose}
+              aria-label="Close conflict resolver"
               className="p-2 hover:bg-white/5 rounded-lg text-gray-400 transition-colors"
             >
               <X size={20} />
diff --git a/src/components/CookieConsentBanner.tsx b/src/components/CookieConsentBanner.tsx
index de0b50de..8fc9535f 100644
--- a/src/components/CookieConsentBanner.tsx
+++ b/src/components/CookieConsentBanner.tsx
@@ -1,84 +1,30 @@
 'use client';
 
-import { useEffect, useRef, useId } from 'react';
+import { useEffect, useId } from 'react';
 import { Shield } from 'lucide-react';
 import { useGdprConsent } from '@/hooks/useGdprConsent';
 import { useScreenReaderAnnouncement } from '@/hooks/useAccessibility';
+import { useFocusTrap } from '@/hooks/useFocusTrap';
 
 /**
- * GDPR Cookie Consent Banner with full focus management:
- * - Traps focus inside the banner while visible
- * - Restores focus to the previously focused element on dismiss
+ * GDPR Cookie Consent Banner with keyboard focus management:
+ * - Traps focus inside the banner and restores it on dismissal
  * - Announces appearance to screen readers
  * - Keyboard: Tab/Shift+Tab cycle within banner; Enter/Space activate buttons
  */
 export function CookieConsentBanner() {
   const { showBanner, accept, reject } = useGdprConsent();
-  const bannerRef = useRef<HTMLDivElement>(null);
-  const previousFocusRef = useRef<HTMLElement | null>(null);
+  const bannerRef = useFocusTrap<HTMLDivElement>(showBanner);
   const announce = useScreenReaderAnnouncement();
   const titleId = useId();
 
-  // Save the element that had focus before the banner appeared, then focus the banner
+  // Announce appearance to screen readers. useFocusTrap moves focus to the first control.
   useEffect(() => {
     if (!showBanner) return;
 
-    previousFocusRef.current = document.activeElement as HTMLElement;
     announce('Cookie consent banner appeared. Please choose your cookie preferences.', 'assertive');
-
-    // Focus the first interactive element inside the banner
-    const raf = requestAnimationFrame(() => {
-      const first = bannerRef.current?.querySelector<HTMLElement>(
-        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
-      );
-      first?.focus();
-    });
-
-    return () => cancelAnimationFrame(raf);
   }, [showBanner, announce]);
 
-  // Restore focus when banner is dismissed
-  useEffect(() => {
-    if (showBanner) return;
-    previousFocusRef.current?.focus();
-    previousFocusRef.current = null;
-  }, [showBanner]);
-
-  // Trap focus inside the banner while it is visible
-  useEffect(() => {
-    if (!showBanner) return;
-
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key !== 'Tab' || !bannerRef.current) return;
-
-      const focusable = Array.from(
-        bannerRef.current.querySelectorAll<HTMLElement>(
-          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
-        ),
-      ).filter((el) => !el.hasAttribute('disabled'));
-
-      if (focusable.length === 0) return;
-
-      const first = focusable[0];
-      const last = focusable[focusable.length - 1];
-
-      if (e.shiftKey) {
-        if (document.activeElement === first) {
-          e.preventDefault();
-          last.focus();
-        }
-      } else {
-        if (document.activeElement === last) {
-          e.preventDefault();
-          first.focus();
-        }
-      }
-    };
-
-    document.addEventListener('keydown', handleKeyDown);
-    return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [showBanner]);
-
   if (!showBanner) return null;
 
   return (
diff --git a/src/components/courses/VideoPreview.tsx b/src/components/courses/VideoPreview.tsx
index 5fc644ed..d279d0e5 100644
--- a/src/components/courses/VideoPreview.tsx
+++ b/src/components/courses/VideoPreview.tsx
@@ -1,6 +1,7 @@
 'use client';
 
-import { useState } from 'react';
+import { useEffect, useId, useRef, useState } from 'react';
+import { useFocusTrap } from '@/hooks/useFocusTrap';
 
 interface VideoPreviewProps {
   videoUrl?: string;
@@ -13,8 +14,26 @@ export default function VideoPreview({
   videoUrl = 'https://www.youtube.com/embed/dQw4w9WgXcQ',
   thumbnailUrl = 'https://static.vecteezy.com/system/resources/previews/053/715/379/non_2x/abstract-green-digital-rain-with-matrix-code-in-futuristic-cyber-background-perfect-for-technology-and-data-themed-visuals-png.png',
   duration = '5:30',
+  onClose,
 }: VideoPreviewProps) {
   const [isOpen, setIsOpen] = useState(false);
+  const closeButtonRef = useRef<HTMLButtonElement>(null);
+  const dialogRef = useFocusTrap<HTMLDivElement>(isOpen, { initialFocusRef: closeButtonRef });
+  const titleId = useId();
+
+  const closePreview = () => {
+    setIsOpen(false);
+    onClose?.();
+  };
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') closePreview();
+    };
+    document.addEventListener('keydown', handleEscape);
+    return () => document.removeEventListener('keydown', handleEscape);
+  }, [isOpen, onClose]);
 
   return (
     <>
@@ -38,12 +57,22 @@ export default function VideoPreview({
 
       {isOpen && (
         <div
+          ref={dialogRef}
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby={titleId}
           className="fixed inset-0 z-50 bg-black/80 backdrop-blur-sm flex items-center justify-center p-4"
-          onClick={() => setIsOpen(false)}
+          onClick={closePreview}
         >
           <div className="relative w-full max-w-4xl" onClick={(e) => e.stopPropagation()}>
+            <h2 id={titleId} className="sr-only">
+              Video preview
+            </h2>
             <button
-              onClick={() => setIsOpen(false)}
+              ref={closeButtonRef}
+              type="button"
+              onClick={closePreview}
+              aria-label="Close video preview"
               className="absolute -top-12 right-0 text-white hover:text-[#00C2FF] transition-colors"
             >
               <svg className="w-8 h-8" fill="none" stroke="currentColor" viewBox="0 0 24 24">
@@ -57,6 +86,7 @@ export default function VideoPreview({
             </button>
             <iframe
               src={videoUrl}
+              title="Video preview"
               className="w-full aspect-video rounded-xl"
               allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
               allowFullScreen
diff --git a/src/components/editor/MediaEmbedder.tsx b/src/components/editor/MediaEmbedder.tsx
index fa051ae1..da285b52 100644
--- a/src/components/editor/MediaEmbedder.tsx
+++ b/src/components/editor/MediaEmbedder.tsx
@@ -1,6 +1,7 @@
-import React, { useId, useState } from 'react';
+import React, { useEffect, useId, useRef, useState } from 'react';
 import { Image as ImageIcon, Youtube as YoutubeIcon } from 'lucide-react';
 import { sanitizeUrl } from '@/utils/sanitize';
+import { useFocusTrap } from '@/hooks/useFocusTrap';
 
 interface MediaEmbedderProps {
   onAddImage: (url: string) => void;
@@ -16,6 +17,19 @@ export const MediaEmbedder: React.FC<MediaEmbedderProps> = ({ onAddImage, onAddY
   const dialogTitleId = `${id}-title`;
   const errorId = `${id}-error`;
   const inputId = `${id}-url`;
+  const urlInputRef = useRef<HTMLInputElement>(null);
+  const dialogRef = useFocusTrap<HTMLDivElement>(isOpen, { initialFocusRef: urlInputRef });
+
+  const closeDialog = () => setIsOpen(false);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') closeDialog();
+    };
+    document.addEventListener('keydown', handleEscape);
+    return () => document.removeEventListener('keydown', handleEscape);
+  }, [isOpen]);
 
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
@@ -31,11 +45,11 @@ export const MediaEmbedder: React.FC<MediaEmbedderProps> = ({ onAddImage, onAddY
       onAddYoutube(safeUrl);
     }
     setUrl('');
-    setIsOpen(false);
+    closeDialog();
   };
 
-  if (!isOpen) {
-    return (
+  return (
+    <>
       <div className="flex gap-2">
         <button
           type="button"
@@ -62,62 +76,63 @@ export const MediaEmbedder: React.FC<MediaEmbedderProps> = ({ onAddImage, onAddY
           <YoutubeIcon className="w-5 h-5" aria-hidden="true" />
         </button>
       </div>
-    );
-  }
-
-  return (
-    <div
-      role="dialog"
-      aria-modal="true"
-      aria-labelledby={dialogTitleId}
-      className="fixed inset-0 z-50 flex items-center justify-center bg-black/50"
-    >
-      <div className="bg-white dark:bg-gray-800 p-6 rounded-lg shadow-lg w-96">
-        <h3 id={dialogTitleId} className="text-lg font-bold mb-4">
-          Add {type === 'image' ? 'Image' : 'YouTube Video'}
-        </h3>
-        <form onSubmit={handleSubmit}>
-          <label htmlFor={inputId} className="sr-only">
-            {type === 'image' ? 'Image URL' : 'YouTube video URL'}
-          </label>
-          <input
-            id={inputId}
-            type="url"
-            value={url}
-            onChange={(e) => {
-              setUrl(e.target.value);
-              setUrlError('');
-            }}
-            placeholder={`Enter ${type} URL...`}
-            className="w-full p-2 border rounded mb-1 dark:bg-gray-700 dark:border-gray-600"
-            aria-describedby={errorId}
-            required
-          />
-          <p
-            id={errorId}
-            role="alert"
-            aria-live="assertive"
-            className="text-red-500 text-sm mb-3 min-h-[1.25rem]"
-          >
-            {urlError}
-          </p>
-          <div className="flex justify-end gap-2">
-            <button
-              type="button"
-              onClick={() => setIsOpen(false)}
-              className="px-4 py-2 text-gray-600 hover:bg-gray-100 rounded"
-            >
-              Cancel
-            </button>
-            <button
-              type="submit"
-              className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
-            >
-              Embed
-            </button>
+      {isOpen ? (
+        <div
+          ref={dialogRef}
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby={dialogTitleId}
+          className="fixed inset-0 z-50 flex items-center justify-center bg-black/50"
+        >
+          <div className="bg-white dark:bg-gray-800 p-6 rounded-lg shadow-lg w-96">
+            <h3 id={dialogTitleId} className="text-lg font-bold mb-4">
+              Add {type === 'image' ? 'Image' : 'YouTube Video'}
+            </h3>
+            <form onSubmit={handleSubmit}>
+              <label htmlFor={inputId} className="sr-only">
+                {type === 'image' ? 'Image URL' : 'YouTube video URL'}
+              </label>
+              <input
+                ref={urlInputRef}
+                id={inputId}
+                type="url"
+                value={url}
+                onChange={(e) => {
+                  setUrl(e.target.value);
+                  setUrlError('');
+                }}
+                placeholder={`Enter ${type} URL...`}
+                className="w-full p-2 border rounded mb-1 dark:bg-gray-700 dark:border-gray-600"
+                aria-describedby={errorId}
+                required
+              />
+              <p
+                id={errorId}
+                role="alert"
+                aria-live="assertive"
+                className="text-red-500 text-sm mb-3 min-h-[1.25rem]"
+              >
+                {urlError}
+              </p>
+              <div className="flex justify-end gap-2">
+                <button
+                  type="button"
+                  onClick={closeDialog}
+                  className="px-4 py-2 text-gray-600 hover:bg-gray-100 rounded"
+                >
+                  Cancel
+                </button>
+                <button
+                  type="submit"
+                  className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
+                >
+                  Embed
+                </button>
+              </div>
+            </form>
           </div>
-        </form>
-      </div>
-    </div>
+        </div>
+      ) : null}
+    </>
   );
 };
diff --git a/src/components/notificationcenter.tsx b/src/components/notificationcenter.tsx
index 35497dbb..71fe0deb 100644
--- a/src/components/notificationcenter.tsx
+++ b/src/components/notificationcenter.tsx
@@ -1,12 +1,24 @@
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-nocheck
 'use client';
-import React, { useState, useRef, useEffect } from 'react';
+import React, { useState, useRef, useEffect, useId } from 'react';
 import Image from 'next/image';
-import { BellOff, Info, CheckCircle, AlertTriangle, XCircle, Message, Book, Settings, Bell, X } from 'lucide-react';
+import {
+  BellOff,
+  Info,
+  CheckCircle,
+  AlertTriangle,
+  XCircle,
+  Message,
+  Book,
+  Settings,
+  Bell,
+  X,
+} from 'lucide-react';
 import { Notification, NotificationType, useNotifications } from '@/providers/Notificationprovider';
 import { EmptyState } from '@/components';
 import { getDateTimeFormat } from '@/utils/intlCache';
+import { useFocusTrap } from '@/hooks/useFocusTrap';
 
 // ──────────────────────────────────────────────────────────────────────────────
 // Icon helpers
@@ -14,12 +26,12 @@ import { getDateTimeFormat } from '@/utils/intlCache';
 
 const TYPE_ICON: Record<NotificationType, React.ReactNode> = {
   info: <Info className="h-5 w-5" />,
-  success: <CheckCircle className='h-5 w-5' />,
-  warning: <AlertTriangle className='h-5 w-5' />,
-  error: <XCircle className='h-5 w-5' />,
-  message: <Message className='h-5 w-5' />,
-  course: <Book className='h-5 w-5' />,
-  system: <Settings className='h-5 w-5' />,
+  success: <CheckCircle className="h-5 w-5" />,
+  warning: <AlertTriangle className="h-5 w-5" />,
+  error: <XCircle className="h-5 w-5" />,
+  message: <Message className="h-5 w-5" />,
+  course: <Book className="h-5 w-5" />,
+  system: <Settings className="h-5 w-5" />,
 };
 
 function timeAgo(date: Date): string {
@@ -84,7 +96,7 @@ function NotificationItem({ notification, onRead, onClear }: NotificationItemPro
             className="notification-item__avatar"
           />
         ) : (
-          {TYPE_ICON[type]}
+          TYPE_ICON[type]
         )}
       </div>
       <div className="notification-item__body">
@@ -103,7 +115,7 @@ function NotificationItem({ notification, onRead, onClear }: NotificationItemPro
         }}
         aria-label="Dismiss notification"
       >
-        <X className='h-4 w-4' />
+        <X className="h-4 w-4" />
       </button>
     </div>
   );
@@ -116,16 +128,20 @@ function NotificationItem({ notification, onRead, onClear }: NotificationItemPro
 interface NotificationBadgeProps {
   count: number;
   onClick: () => void;
+  expanded: boolean;
+  controls: string;
 }
 
-export function NotificationBadge({ count, onClick }: NotificationBadgeProps) {
+export function NotificationBadge({ count, onClick, expanded, controls }: NotificationBadgeProps) {
   return (
     <button
       className="notification-badge-btn"
       onClick={onClick}
       aria-label={`Notifications${count > 0 ? `, ${count} unread` : ''}`}
+      aria-expanded={expanded}
+      aria-controls={controls}
     >
-      <Bell className='h-5 w-5' aria-hidden='true' />
+      <Bell className="h-5 w-5" aria-hidden="true" />
       {count > 0 && <span className="notification-count">{count > 99 ? '99+' : count}</span>}
     </button>
   );
@@ -140,12 +156,15 @@ export function NotificationCenter() {
     useNotifications();
 
   const [open, setOpen] = useState(false);
-  const panelRef = useRef<HTMLDivElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const panelRef = useFocusTrap<HTMLDivElement>(open);
+  const titleId = useId();
+  const panelId = useId();
 
   // Close on outside click
   useEffect(() => {
     function handleOutside(e: MouseEvent) {
-      if (panelRef.current && !panelRef.current.contains(e.target as Node)) {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
         setOpen(false);
       }
     }
@@ -160,14 +179,35 @@ export function NotificationCenter() {
     return () => clearTimeout(timer);
   }, [open, markAllAsRead]);
 
+  useEffect(() => {
+    if (!open) return;
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') setOpen(false);
+    };
+    document.addEventListener('keydown', handleEscape);
+    return () => document.removeEventListener('keydown', handleEscape);
+  }, [open]);
+
   return (
-    <div className="notification-center" ref={panelRef}>
-      <NotificationBadge count={unreadCount} onClick={() => setOpen((v) => !v)} />
+    <div className="notification-center" ref={containerRef}>
+      <NotificationBadge
+        count={unreadCount}
+        onClick={() => setOpen((v) => !v)}
+        expanded={open}
+        controls={panelId}
+      />
 
       {open && (
-        <div className="notification-panel" role="dialog" aria-label="Notifications">
+        <div
+          ref={panelRef}
+          id={panelId}
+          className="notification-panel"
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby={titleId}
+        >
           <div className="notification-panel__header">
-            <h2>Notifications</h2>
+            <h2 id={titleId}>Notifications</h2>
             <div className="notification-panel__actions">
               {unreadCount > 0 && (
                 <button onClick={markAllAsRead} className="btn-link">
diff --git a/src/components/ui/Modal.tsx b/src/components/ui/Modal.tsx
index 46c5a636..19a1831f 100644
--- a/src/components/ui/Modal.tsx
+++ b/src/components/ui/Modal.tsx
@@ -2,7 +2,8 @@
 
 import { useEffect, useId } from 'react';
 import { X } from 'lucide-react';
-import { useFocusTrap, useScreenReaderAnnouncement } from '@/hooks/useAccessibility';
+import { useScreenReaderAnnouncement } from '@/hooks/useAccessibility';
+import { useFocusTrap } from '@/hooks/useFocusTrap';
 import { ErrorBoundary } from '@/components/errors/ErrorBoundarySystem';
 
 export type ModalSize = 'sm' | 'md' | 'lg' | 'xl' | 'full';
@@ -30,8 +31,8 @@ export interface ModalProps {
 }
 
 /**
- * Accessible modal dialog with focus trap, Escape-to-close, and screen reader announcements.
- * Uses the existing `useFocusTrap` hook from `useAccessibility`.
+ * Accessible modal dialog with keyboard focus containment, focus restoration,
+ * Escape-to-close, and screen reader announcements.
  *
  * `onClose` now receives an optional reason ('escape' | 'backdrop' | 'button')
  * so consumers that need to distinguish an ambient dismiss gesture from an
@@ -40,14 +41,6 @@ export interface ModalProps {
  * user with a feedback prompt. Existing `() => void` handlers are unaffected;
  * they simply ignore the extra argument.
  *
- * NOTE on native `<dialog>`: this was evaluated as a follow-up (native
- * top-layer stacking, a real `::backdrop`, built-in inertness of background
- * content) but jsdom 26, which this repo's Vitest suite runs on, does not
- * implement `HTMLDialogElement.showModal()`/`close()` — every test that
- * renders a Modal (this file's suite, plus any test touching the 9 current
- * consumers) would throw immediately. Revisit once the test environment
- * upgrades to a jsdom version with dialog support, or the suite moves to a
- * real-browser runner (e.g. Playwright component tests) for this component.
  */
 export function Modal({
   isOpen,
@@ -58,7 +51,7 @@ export function Modal({
   className = '',
 }: ModalProps) {
   const titleId = useId();
-  const containerRef = useFocusTrap(isOpen);
+  const containerRef = useFocusTrap<HTMLDivElement>(isOpen);
   const announce = useScreenReaderAnnouncement();
 
   // Announce open/close and lock body scroll
@@ -97,7 +90,7 @@ export function Modal({
 
       {/* Dialog */}
       <div
-        ref={containerRef as React.RefObject<HTMLDivElement>}
+        ref={containerRef}
         role="dialog"
         aria-modal="true"
         aria-labelledby={titleId}
@@ -130,4 +123,4 @@ export function Modal({
       </div>
     </>
   );
-}
\ No newline at end of file
+}
diff --git a/src/components/ui/__tests__/Modal.test.tsx b/src/components/ui/__tests__/Modal.test.tsx
index 868cd364..f2892dbb 100644
--- a/src/components/ui/__tests__/Modal.test.tsx
+++ b/src/components/ui/__tests__/Modal.test.tsx
@@ -1,16 +1,9 @@
 import React from 'react';
-import { render, screen, fireEvent, act } from '@testing-library/react';
+import { render, screen, fireEvent } from '@testing-library/react';
 import { vi } from 'vitest';
 import { Modal, ModalSize } from '../Modal';
 
-// ---------------------------------------------------------------------------
-// We keep a module-level ref handle so individual tests can point the
-// useFocusTrap ref at the real rendered dialog element.
-// ---------------------------------------------------------------------------
-let focusTrapRefHandle: React.MutableRefObject<HTMLElement | null> = { current: null };
-
 vi.mock('@/hooks/useAccessibility', () => ({
-  useFocusTrap: (_isActive: boolean) => focusTrapRefHandle,
   useScreenReaderAnnouncement: () => vi.fn(),
 }));
 
@@ -90,19 +83,8 @@ describe('Modal', () => {
   });
 });
 
-// ---------------------------------------------------------------------------
-// Focus-trap behaviour (initial focus, Tab wrapping, focus restoration)
-// These tests let the real useFocusTrap logic run by pointing the ref at the
-// actual dialog element after render.
-// ---------------------------------------------------------------------------
 describe('Modal – focus behaviours', () => {
-  beforeEach(() => {
-    // Reset the ref handle before every test
-    focusTrapRefHandle = { current: null };
-  });
-
-  it('moves focus into the dialog on open', async () => {
-    // Render with a trigger button so we have a natural "previously-focused" element
+  it('keeps focus inside the dialog and returns it to the trigger on close', () => {
     const Wrapper = () => {
       const [open, setOpen] = React.useState(false);
       return (
@@ -110,9 +92,8 @@ describe('Modal – focus behaviours', () => {
           <button id="trigger" onClick={() => setOpen(true)}>
             Open
           </button>
-          <Modal isOpen={open} onClose={() => setOpen(false)} title="Focus Test">
-            <button id="first-focusable">First</button>
-            <button id="second-focusable">Second</button>
+          <Modal isOpen={open} onClose={() => setOpen(false)} title="Focus test">
+            <button type="button">Last dialog action</button>
           </Modal>
         </>
       );
@@ -121,99 +102,20 @@ describe('Modal – focus behaviours', () => {
     render(<Wrapper />);
     const trigger = screen.getByText('Open');
     trigger.focus();
-    expect(document.activeElement).toBe(trigger);
-
-    // Open the modal
-    await act(async () => {
-      fireEvent.click(trigger);
-    });
-
-    // Point the mocked ref at the real dialog so useFocusTrap can act on it
-    const dialog = screen.getByRole('dialog');
-    focusTrapRefHandle.current = dialog as HTMLElement;
-
-    // Simulate what useFocusTrap does: focus the first focusable child
-    const focusable = dialog.querySelectorAll<HTMLElement>(
-      'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])',
-    );
-    if (focusable.length > 0) focusable[0].focus();
-
-    expect(dialog.contains(document.activeElement)).toBe(true);
-  });
-
-  it('returns focus to the trigger element after the modal closes', async () => {
-    const onClose = vi.fn();
-    const Wrapper = () => {
-      const [open, setOpen] = React.useState(true);
-      return (
-        <>
-          <button id="trigger">Trigger</button>
-          <Modal
-            isOpen={open}
-            onClose={() => {
-              onClose();
-              setOpen(false);
-            }}
-            title="Restore Focus Test"
-          >
-            <button id="inside">Inside</button>
-          </Modal>
-        </>
-      );
-    };
+    fireEvent.click(trigger);
 
-    render(<Wrapper />);
+    const closeButton = screen.getByLabelText('Close dialog');
+    const lastAction = screen.getByRole('button', { name: 'Last dialog action' });
+    expect(document.activeElement).toBe(closeButton);
 
-    const trigger = document.getElementById('trigger') as HTMLElement;
-    const dialog = screen.getByRole('dialog');
-    focusTrapRefHandle.current = dialog as HTMLElement;
+    lastAction.focus();
+    fireEvent.keyDown(document, { key: 'Tab' });
+    expect(document.activeElement).toBe(closeButton);
 
-    // Simulate the hook saving the previously-focused element and focus inside the modal
-    trigger.focus();
-    const previousFocus = document.activeElement as HTMLElement;
-    const insideBtn = screen.getByText('Inside');
-    insideBtn.focus();
-    expect(document.activeElement).toBe(insideBtn);
-
-    // Close the modal and verify focus is restored
-    await act(async () => {
-      fireEvent.click(screen.getByLabelText('Close dialog'));
-    });
-
-    // Simulate what the useFocusTrap cleanup does
-    previousFocus.focus();
+    fireEvent.keyDown(document, { key: 'Tab', shiftKey: true });
+    expect(document.activeElement).toBe(lastAction);
 
+    fireEvent.click(closeButton);
     expect(document.activeElement).toBe(trigger);
-    expect(onClose).toHaveBeenCalledTimes(1);
-  });
-
-  it('keeps focus inside the dialog (Tab does not leave)', async () => {
-    render(
-      <Modal {...defaultProps}>
-        <button id="btn-a">A</button>
-        <button id="btn-b">B</button>
-      </Modal>,
-    );
-
-    const dialog = screen.getByRole('dialog');
-    focusTrapRefHandle.current = dialog as HTMLElement;
-
-    const focusable = Array.from(
-      dialog.querySelectorAll<HTMLElement>(
-        'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])',
-      ),
-    );
-
-    // Focus the last focusable element, then simulate Tab — focus should wrap to first
-    const last = focusable[focusable.length - 1];
-    last.focus();
-    expect(document.activeElement).toBe(last);
-
-    // Simulate Tab wrapping: focus moves to first element inside the trap
-    fireEvent.keyDown(dialog, { key: 'Tab', shiftKey: false });
-    // After Tab on the last element the trap wraps back to the first
-    focusable[0].focus(); // mirrors what trapFocus does
-
-    expect(dialog.contains(document.activeElement)).toBe(true);
   });
 });
diff --git a/src/hooks/__tests__/useFocusTrap.test.tsx b/src/hooks/__tests__/useFocusTrap.test.tsx
new file mode 100644
index 00000000..f05a2670
--- /dev/null
+++ b/src/hooks/__tests__/useFocusTrap.test.tsx
@@ -0,0 +1,51 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { useRef, useState } from 'react';
+import { useFocusTrap } from '../useFocusTrap';
+
+function FocusTrapHarness() {
+  const [open, setOpen] = useState(false);
+  const initialFocusRef = useRef<HTMLButtonElement>(null);
+  const dialogRef = useFocusTrap<HTMLDivElement>(open, { initialFocusRef });
+
+  return (
+    <>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open dialog
+      </button>
+      {open ? (
+        <div ref={dialogRef} role="dialog" aria-modal="true" aria-label="Test dialog">
+          <button ref={initialFocusRef} type="button">
+            First action
+          </button>
+          <button type="button" onClick={() => setOpen(false)}>
+            Close dialog
+          </button>
+        </div>
+      ) : null}
+    </>
+  );
+}
+
+describe('useFocusTrap', () => {
+  it('focuses the requested element, wraps Tab navigation, and restores the opener', () => {
+    render(<FocusTrapHarness />);
+
+    const opener = screen.getByRole('button', { name: 'Open dialog' });
+    opener.focus();
+    fireEvent.click(opener);
+
+    const firstAction = screen.getByRole('button', { name: 'First action' });
+    const closeButton = screen.getByRole('button', { name: 'Close dialog' });
+    expect(document.activeElement).toBe(firstAction);
+
+    closeButton.focus();
+    fireEvent.keyDown(document, { key: 'Tab' });
+    expect(document.activeElement).toBe(firstAction);
+
+    fireEvent.keyDown(document, { key: 'Tab', shiftKey: true });
+    expect(document.activeElement).toBe(closeButton);
+
+    fireEvent.click(closeButton);
+    expect(document.activeElement).toBe(opener);
+  });
+});
diff --git a/src/hooks/useAccessibility.tsx b/src/hooks/useAccessibility.tsx
index 4145cd00..26cbe987 100644
--- a/src/hooks/useAccessibility.tsx
+++ b/src/hooks/useAccessibility.tsx
@@ -1,13 +1,12 @@
 import { useEffect, useRef, useState, useCallback, useContext, useMemo } from 'react';
 import { AccessibilityContext } from '@/components/accessibility/AccessibilityContext';
 import {
-  getFocusableElements,
-  trapFocus,
   announceToScreenReader,
   checkAccessibilityIssues,
   AccessibilityIssue,
 } from '@/utils/accessibilityUtils';
 import type { AccessibilityContextValue } from '@/components/accessibility/AccessibilityContext';
+import { useFocusTrap as useSharedFocusTrap } from '@/hooks/useFocusTrap';
 
 /**
  * Global accessibility context with a safe fallback outside `AccessibilityProvider`.
@@ -59,45 +58,7 @@ export function useKeyboardNavigation(enabled: boolean = true) {
  * Hook for focus trap (modals, dialogs)
  */
 export function useFocusTrap(isActive: boolean = false) {
-  const containerRef = useRef<HTMLElement>(null);
-  const previousFocusRef = useRef<HTMLElement | null>(null);
-
-  useEffect(() => {
-    if (!isActive || !containerRef.current) return;
-
-    const container = containerRef.current;
-    previousFocusRef.current = document.activeElement as HTMLElement;
-
-    const focusableElements = getFocusableElements(container);
-    let removedTabIndex = false;
-    if (focusableElements.length > 0) {
-      focusableElements[0]?.focus();
-    } else {
-      if (!container.hasAttribute('tabindex')) {
-        container.setAttribute('tabindex', '-1');
-        removedTabIndex = true;
-      }
-      container.focus();
-    }
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (containerRef.current) {
-        trapFocus(containerRef.current, event);
-      }
-    };
-
-    document.addEventListener('keydown', handleKeyDown);
-
-    return () => {
-      document.removeEventListener('keydown', handleKeyDown);
-      if (removedTabIndex) {
-        container.removeAttribute('tabindex');
-      }
-      previousFocusRef.current?.focus();
-    };
-  }, [isActive]);
-
-  return containerRef;
+  return useSharedFocusTrap<HTMLElement>(isActive);
 }
 
 /**
diff --git a/src/hooks/useFocusTrap.ts b/src/hooks/useFocusTrap.ts
new file mode 100644
index 00000000..3b4d2251
--- /dev/null
+++ b/src/hooks/useFocusTrap.ts
@@ -0,0 +1,94 @@
+import { useEffect, useRef, type RefObject } from 'react';
+import { getFocusableElements } from '@/utils/accessibilityUtils';
+
+export interface UseFocusTrapOptions {
+  /** Element to focus when the trap becomes active. Falls back to the first control. */
+  initialFocusRef?: RefObject<HTMLElement | null>;
+  /** Whether to return focus to the element that opened the dialog. Defaults to true. */
+  restoreFocus?: boolean;
+}
+
+/**
+ * Keeps keyboard focus inside an active dialog and returns it to its opener on close.
+ *
+ * The hook deliberately discovers focusable elements for each keyboard event so controls
+ * added, disabled, or removed while a dialog is open are handled correctly.
+ */
+export function useFocusTrap<T extends HTMLElement = HTMLDivElement>(
+  isActive: boolean,
+  { initialFocusRef, restoreFocus = true }: UseFocusTrapOptions = {},
+) {
+  const containerRef = useRef<T>(null);
+  const previouslyFocusedRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (!isActive || !containerRef.current) return;
+
+    const container = containerRef.current;
+    previouslyFocusedRef.current =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+
+    const focusInitialElement = () => {
+      const requestedElement = initialFocusRef?.current;
+      const fallbackElement = getFocusableElements(container)[0];
+      const target =
+        requestedElement && container.contains(requestedElement)
+          ? requestedElement
+          : fallbackElement;
+
+      if (target) {
+        target.focus();
+        return;
+      }
+
+      if (!container.hasAttribute('tabindex')) container.setAttribute('tabindex', '-1');
+      container.focus();
+    };
+
+    focusInitialElement();
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Tab') return;
+
+      const focusableElements = getFocusableElements(container);
+      if (focusableElements.length === 0) {
+        event.preventDefault();
+        container.focus();
+        return;
+      }
+
+      const first = focusableElements[0];
+      const last = focusableElements[focusableElements.length - 1];
+      const activeElement = document.activeElement;
+
+      if (event.shiftKey && (activeElement === first || !container.contains(activeElement))) {
+        event.preventDefault();
+        last.focus();
+      } else if (
+        !event.shiftKey &&
+        (activeElement === last || !container.contains(activeElement))
+      ) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+
+    const handleFocusIn = (event: FocusEvent) => {
+      if (!container.contains(event.target as Node)) focusInitialElement();
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    document.addEventListener('focusin', handleFocusIn);
+
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+      document.removeEventListener('focusin', handleFocusIn);
+      if (restoreFocus && previouslyFocusedRef.current?.isConnected) {
+        previouslyFocusedRef.current.focus();
+      }
+      previouslyFocusedRef.current = null;
+    };
+  }, [initialFocusRef, isActive, restoreFocus]);
+
+  return containerRef;
+}