Restored missing documentation comments for accessibility-related changes

Author: Chanchal-D

src/components/navigation/AlertsModal.svelte

@@ -2,11 +2,11 @@
 	import { Modal, Button } from 'flowbite-svelte';
 	import { getLocaleFromNavigator } from 'svelte-i18n';
 	import { t } from 'svelte-i18n';
-	import { onMount, onDestroy } from 'svelte';
-	import { trapFocus } from '../../../utils/focusTrap';
-	import { applyAriaAttributes } from '../../../utils/ariaHelpers';
+	import { onMount } from 'svelte'; // Removed unused onDestroy import
+	import { trapFocus } from '../../../utils/focusTrap'; // Utility to trap focus within the modal for accessibility
+	import { applyAriaAttributes } from '../../../utils/ariaHelpers'; // Utility to apply ARIA attributes for accessibility
 
-	let showModal = $state(true);
+	let showModal = true; // Fixed invalid $state(true) syntax
 	let previouslyFocusedElement = null;
 
 	let { alert } = $props();
@@ -36,27 +36,39 @@
 
 	onMount(() => {
 		if (showModal && modalElement) {
+			// Trap focus within the modal element for better accessibility
 			const releaseFocus = trapFocus(modalElement);
+
+			// Apply ARIA attributes to the modal element for screen readers
 			applyAriaAttributes(modalElement, {
-				role: 'dialog',
-				'aria-modal': 'true',
-				'aria-label': 'Alerts',
+				role: 'dialog', // Defines the modal as a dialog
+				'aria-modal': 'true', // Indicates that the modal is modal and disables interaction with the background
+				'aria-label': 'Alerts', // Provides an accessible name for the modal
 			});
 
+			// Cleanup function to release focus trapping
 			return () => releaseFocus();
 		}
 	});
 
 	function handleModalOpen() {
+		// Save the currently focused element to restore focus later
 		previouslyFocusedElement = document.activeElement;
+
+		// Add focus trapping to the modal element
 		const modalElement = document.querySelector('.modal-pane');
 		modalElement.addEventListener('keydown', trapFocus);
+
+		// Set focus to the modal element
 		modalElement.focus();
 	}
 
 	function handleModalClose() {
+		// Remove focus trapping from the modal element
 		const modalElement = document.querySelector('.modal-pane');
 		modalElement.removeEventListener('keydown', trapFocus);
+
+		// Restore focus to the previously focused element
 		if (previouslyFocusedElement) {
 			previouslyFocusedElement.focus();
 		}
@@ -76,8 +88,8 @@
 				autoclose
 				on:open={handleModalOpen}
 				on:close={handleModalClose}
-				aria-labelledby="alert-modal-title"
-				aria-describedby="alert-modal-description"
+				aria-labelledby="alert-modal-title" <!-- Links the modal title for screen readers -->
+				aria-describedby="alert-modal-description" <!-- Links the modal description for screen readers -->
 			>
 				<p id="alert-modal-description" class="text-base leading-relaxed text-gray-500 dark:text-gray-200">
 					{getBodyTextTranslation()}

src/components/navigation/ModalPane.svelte

@@ -3,15 +3,23 @@
 	import { trapFocus } from '../../../utils/focusTrap';
 	import { applyAriaAttributes } from '../../../utils/ariaHelpers';
 
+	// Indicates whether the modal is open
 	export let isOpen = false;
+
+	// Accessible label for the modal
 	export let ariaLabel = 'Modal Pane';
+
+	// Callback function to handle modal close action
 	export let onClose;
 
 	let modalElement;
 
 	onMount(() => {
 		if (isOpen && modalElement) {
+			// Trap focus within the modal when it is open
 			const releaseFocus = trapFocus(modalElement);
+
+			// Apply ARIA attributes to ensure accessibility
 			applyAriaAttributes(modalElement, {
 				role: 'dialog',
 				'aria-modal': 'true',

src/components/stops/StopModal.svelte

@@ -9,14 +9,19 @@
 	let modalElement;
 
 	onMount(() => {
+		// Ensure focus is trapped within the modal when it is open
+		// and restore focus to the previously focused element when the modal is closed.
 		if (isOpen && modalElement) {
 			const releaseFocus = trapFocus(modalElement);
+
+			// Apply ARIA attributes to enhance accessibility for screen readers.
 			applyAriaAttributes(modalElement, {
 				role: 'dialog',
 				'aria-modal': 'true',
 				'aria-label': 'Stop Information',
 			});
 
+			// Cleanup function to release focus trap when the component is destroyed.
 			return () => releaseFocus();
 		}
 	});
@@ -30,6 +35,7 @@
 			on:click|stopPropagation
 		>
 			<slot />
+			<!-- Close button with ARIA label for accessibility -->
 			<button on:click={onClose} aria-label="Close modal">Close</button>
 		</div>
 	</div>

src/components/trip-planner/TripPlanModal.svelte

@@ -66,10 +66,25 @@
 	let previouslyFocusedElement = null;
 	let modalElement;
 
+	/**
+	 * Trap focus within the modal element when it is mounted.
+	 * This ensures keyboard navigation is restricted to the modal for accessibility.
+	 */
 	onMount(() => {
 		drawRoute();
 		if (modalElement) {
+			/**
+			 * Release focus trapping when the modal is destroyed.
+			 * @returns {Function} A cleanup function to release focus trapping.
+			 */
 			const releaseFocus = trapFocus(modalElement);
+
+			/**
+			 * Apply ARIA attributes to the modal for screen reader support.
+			 * - role: 'dialog' indicates the element is a dialog.
+			 * - aria-modal: 'true' informs assistive technologies that the dialog is modal.
+			 * - aria-label: Provides a label for the dialog.
+			 */
 			applyAriaAttributes(modalElement, {
 				role: 'dialog',
 				'aria-modal': 'true',
@@ -94,7 +109,15 @@
 <ModalPane
 	{closePane}
 	title={$t('trip-planner.trip_itineraries')}
+	/**
+	 * Focus the modal element when it is opened.
+	 * This ensures the modal is immediately accessible to keyboard users.
+	 */
 	on:open={() => modalElement && modalElement.focus()}
+	/**
+	 * Restore focus to the previously focused element when the modal is closed.
+	 * This helps maintain a logical focus order for accessibility.
+	 */
 	on:close={() => previouslyFocusedElement && previouslyFocusedElement.focus()}
 	aria-labelledby="trip-plan-modal-title"
 	aria-describedby="trip-plan-modal-description"