Merge pull request #684 from ProgressPlanner/ari/a11y-fixes-2025-10-24

A11y fixes and improvements for v1.9.0

Author: ilicfilip

assets/css/admin.css

@@ -24,6 +24,26 @@
 	--prpl-font-size-6xl: 4.5rem;     /* 72px */
 }
 
+/*------------------------------------*\
+	Accessibility: Skip link
+\*------------------------------------*/
+.prpl-skip-link {
+	position: absolute;
+	top: -40px;
+	left: 0;
+	background: var(--prpl-color-button-primary);
+	color: var(--prpl-color-button-primary-text);
+	padding: 8px 16px;
+	text-decoration: none;
+	border-radius: var(--prpl-border-radius);
+	z-index: 100000;
+}
+
+.prpl-skip-link:focus {
+	top: 10px;
+	left: 10px;
+}
+
 /*------------------------------------*\
 	Progress Planner dashboard page.
 \*------------------------------------*/

assets/js/tour.js

@@ -101,3 +101,8 @@ function prplStartTour() {
 			.replace( 'show-tour=true', '' )
 	);
 }
+
+// Add event listener for tour button.
+document
+	.getElementById( 'prpl-start-tour-icon-button' )
+	?.addEventListener( 'click', prplStartTour );

assets/js/web-components/prpl-tooltip.js

@@ -36,6 +36,12 @@ customElements.define(
 			const tooltipContent = document.createElement( 'div' );
 			tooltipContent.className = 'prpl-tooltip';
 			tooltipContent.setAttribute( 'data-tooltip-content', '' );
+			tooltipContent.setAttribute( 'role', 'tooltip' );
+			tooltipContent.setAttribute( 'aria-hidden', 'true' );
+			// Generate a unique ID for the tooltip.
+			const tooltipId =
+				'prpl-tooltip-' + Math.random().toString( 36 ).substr( 2, 9 );
+			tooltipContent.setAttribute( 'id', tooltipId );
 
 			// Move content inside the tooltip container
 			while ( contentSlot?.childNodes.length ) {
@@ -61,6 +67,8 @@ customElements.define(
 
 			// Add data attribute to the open button.
 			openButton.setAttribute( 'data-tooltip-action', 'open-tooltip' );
+			// Connect button to tooltip for screen readers.
+			openButton.setAttribute( 'aria-describedby', tooltipId );
 
 			openSlot?.remove(); // Remove slot element
 			openIconSlot?.remove(); // Remove slot element
@@ -108,16 +116,20 @@ customElements.define(
 
 			// Open the tooltip.
 			openTooltipButton?.addEventListener( 'click', () => {
-				thisObj
-					.querySelector( '[data-tooltip-content]' )
-					.setAttribute( 'data-tooltip-visible', 'true' );
+				const tooltip = thisObj.querySelector(
+					'[data-tooltip-content]'
+				);
+				tooltip.setAttribute( 'data-tooltip-visible', 'true' );
+				tooltip.removeAttribute( 'aria-hidden' );
 			} );
 
 			// Close the tooltip.
 			closeTooltipButton?.addEventListener( 'click', () => {
-				thisObj
-					.querySelector( '[data-tooltip-content]' )
-					.removeAttribute( 'data-tooltip-visible' );
+				const tooltip = thisObj.querySelector(
+					'[data-tooltip-content]'
+				);
+				tooltip.removeAttribute( 'data-tooltip-visible' );
+				tooltip.setAttribute( 'aria-hidden', 'true' );
 			} );
 		};
 	}

assets/js/widgets/todo.js

@@ -1,10 +1,10 @@
-/* global prplSuggestedTask, prplTerms */
+/* global prplSuggestedTask, prplTerms, prplL10n */
 /*
  * Widget: Todo
  *
  * A widget that displays a todo list.
  *
- * Dependencies: wp-api, progress-planner/suggested-task, wp-util, wp-a11y, progress-planner/grid-masonry, progress-planner/celebrate, progress-planner/suggested-task-terms
+ * Dependencies: wp-api, progress-planner/suggested-task, wp-util, wp-a11y, progress-planner/grid-masonry, progress-planner/celebrate, progress-planner/suggested-task-terms, progress-planner/l10n
  */
 
 const prplTodoWidget = {
@@ -160,6 +160,11 @@ const prplTodoWidget = {
 					// Remove the loader.
 					prplTodoWidget.removeLoader();
 
+					// Announce to screen readers.
+					prplTodoWidget.announceToScreenReader(
+						prplL10n( 'taskAddedSuccessfully' )
+					);
+
 					// Resize the grid items.
 					window.dispatchEvent(
 						new CustomEvent( 'prpl/grid/resize' )
@@ -174,12 +179,40 @@ const prplTodoWidget = {
 			} );
 	},
 
+	/**
+	 * Announce to screen readers.
+	 *
+	 * @param {string} message  The message to announce.
+	 * @param {string} priority The priority ('polite' or 'assertive').
+	 */
+	announceToScreenReader: ( message, priority = 'polite' ) => {
+		// Use WordPress a11y speak if available.
+		if ( 'undefined' !== typeof wp && wp.a11y && wp.a11y.speak ) {
+			wp.a11y.speak( message, priority );
+		} else {
+			// Fallback to ARIA live region.
+			const liveRegion = document.getElementById(
+				'todo-aria-live-region'
+			);
+			if ( liveRegion ) {
+				liveRegion.textContent = message;
+				setTimeout( () => {
+					liveRegion.textContent = '';
+				}, 1000 );
+			}
+		}
+	},
+
 	/**
 	 * Add the loader.
 	 */
 	addLoader: () => {
 		const loader = document.createElement( 'span' );
+		const loadingTasksText = prplL10n( 'loadingTasks' );
 		loader.className = 'prpl-loader';
+		loader.setAttribute( 'role', 'status' );
+		loader.setAttribute( 'aria-live', 'polite' );
+		loader.innerHTML = `<span class="screen-reader-text">${ loadingTasksText }</span>`;
 		document.getElementById( 'todo-list' ).appendChild( loader );
 	},
 
@@ -220,12 +253,25 @@ const prplTodoWidget = {
 	 * Delete all completed tasks.
 	 */
 	deleteAllCompletedTasks: () => {
-		document
-			.querySelectorAll( '#todo-list-completed .prpl-suggested-task' )
-			.forEach( ( item ) => {
-				const postId = parseInt( item.getAttribute( 'data-post-id' ) );
-				prplSuggestedTask.trash( postId );
-			} );
+		const items = document.querySelectorAll(
+			'#todo-list-completed .prpl-suggested-task'
+		);
+		const itemCount = items.length;
+
+		items.forEach( ( item ) => {
+			const postId = parseInt( item.getAttribute( 'data-post-id' ) );
+			prplSuggestedTask.trash( postId );
+		} );
+
+		// Announce to screen readers.
+		const tasksWord =
+			itemCount === 1
+				? prplL10n( 'taskDeleted' )
+				: prplL10n( 'tasksDeleted' );
+		prplTodoWidget.announceToScreenReader(
+			`${ itemCount } ${ tasksWord }`,
+			'assertive'
+		);
 
 		// Resize event will be triggered by the trash function.
 	},
@@ -237,6 +283,27 @@ document
 		window.dispatchEvent( new CustomEvent( 'prpl/grid/resize' ) );
 	} );
 
+// Add event listener for delete all button.
+document
+	.getElementById( 'todo-list-completed-delete-all' )
+	?.addEventListener( 'click', () => {
+		prplTodoWidget.showDeleteAllPopover();
+	} );
+
+// Add event listener for cancel button in delete all popover.
+document
+	.getElementById( 'todo-list-completed-delete-all-cancel' )
+	?.addEventListener( 'click', () => {
+		prplTodoWidget.closeDeleteAllPopover();
+	} );
+
+// Add event listener for confirm button in delete all popover.
+document
+	.getElementById( 'todo-list-completed-delete-all-confirm' )
+	?.addEventListener( 'click', () => {
+		prplTodoWidget.deleteAllCompletedTasksAndClosePopover();
+	} );
+
 document.addEventListener( 'prpl/suggestedTask/itemInjected', ( event ) => {
 	if ( 'todo-list' !== event.detail.listId ) {
 		return;

classes/admin/class-enqueue.php

@@ -402,6 +402,13 @@ public function get_localized_strings() {
 			'showAllRecommendations'       => \esc_html__( 'Show all recommendations', 'progress-planner' ),
 			'showFewerRecommendations'     => \esc_html__( 'Show fewer recommendations', 'progress-planner' ),
 			'loadingTasks'                 => \esc_html__( 'Loading tasks...', 'progress-planner' ),
+			'taskAddedSuccessfully'        => \esc_html__( 'Task added successfully', 'progress-planner' ),
+			'tasksDeleted'                 => \esc_html__( 'Completed tasks deleted', 'progress-planner' ),
+			'taskDeleted'                  => \esc_html__( 'Completed task deleted', 'progress-planner' ),
+			'moveUp'                       => \esc_html__( 'Move up', 'progress-planner' ),
+			'moveDown'                     => \esc_html__( 'Move down', 'progress-planner' ),
+			/* translators: %d: The number of points. */
+			'fixThisIssue'                 => \esc_html__( 'Fix this issue for %d points', 'progress-planner' ),
 		];
 	}
 

classes/admin/widgets/class-todo.php

@@ -50,8 +50,9 @@ public function the_todo_list() {
 
 		<form id="create-todo-item">
 			<input type="text" id="new-todo-content" placeholder="<?php \esc_attr_e( 'Add a new task', 'progress-planner' ); ?>" aria-label="<?php \esc_attr_e( 'Add a new task', 'progress-planner' ); ?>" required />
-			<button type="submit" title="<?php \esc_attr_e( 'Add', 'progress-planner' ); ?>">
-				<span class="dashicons dashicons-plus-alt2"></span>
+			<button type="submit" aria-label="<?php \esc_attr_e( 'Add task', 'progress-planner' ); ?>">
+				<span class="dashicons dashicons-plus-alt2" aria-hidden="true"></span>
+				<span class="screen-reader-text"><?php \esc_html_e( 'Add task', 'progress-planner' ); ?></span>
 			</button>
 		</form>
 		<details id="todo-list-completed-details">
@@ -63,7 +64,7 @@ public function the_todo_list() {
 				</span>
 			</summary>
 			<div id="todo-list-completed-delete-all-wrapper">
-				<button id="todo-list-completed-delete-all" onclick="prplTodoWidget.showDeleteAllPopover()">
+				<button id="todo-list-completed-delete-all">
 					<span style="display: inline-block; width: 18px; height: 18px;">
 						<svg role="img" aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48"><path fill="#9ca3af" d="M32.99 47.88H15.01c-3.46 0-6.38-2.7-6.64-6.15L6.04 11.49l-.72.12c-.82.14-1.59-.41-1.73-1.22-.14-.82.41-1.59 1.22-1.73.79-.14 1.57-.26 2.37-.38h.02c2.21-.33 4.46-.6 6.69-.81v-.72c0-3.56 2.74-6.44 6.25-6.55 2.56-.08 5.15-.08 7.71 0 3.5.11 6.25 2.99 6.25 6.55v.72c2.24.2 4.48.47 6.7.81.79.12 1.59.25 2.38.39.82.14 1.36.92 1.22 1.73-.14.82-.92 1.36-1.73 1.22l-.72-.12-2.33 30.24c-.27 3.45-3.18 6.15-6.64 6.15Zm-17.98-3h17.97c1.9 0 3.51-1.48 3.65-3.38l2.34-30.46c-2.15-.3-4.33-.53-6.48-.7h-.03c-5.62-.43-11.32-.43-16.95 0h-.03c-2.15.17-4.33.4-6.48.7l2.34 30.46c.15 1.9 1.75 3.38 3.65 3.38ZM24 7.01c2.37 0 4.74.07 7.11.22v-.49c0-1.93-1.47-3.49-3.34-3.55-2.5-.08-5.03-.08-7.52 0-1.88.06-3.34 1.62-3.34 3.55v.49c2.36-.15 4.73-.22 7.11-.22Zm5.49 32.26h-.06c-.83-.03-1.47-.73-1.44-1.56l.79-20.65c.03-.83.75-1.45 1.56-1.44.83.03 1.47.73 1.44 1.56l-.79 20.65c-.03.81-.7 1.44-1.5 1.44Zm-10.98 0c-.8 0-1.47-.63-1.5-1.44l-.79-20.65c-.03-.83.61-1.52 1.44-1.56.84 0 1.52.61 1.56 1.44l.79 20.65c.03.83-.61 1.52-1.44 1.56h-.06Z"></path></svg>
 					</span>
@@ -83,13 +84,13 @@ public function the_todo_list() {
 			</div>
 
 			<div class="prpl-buttons-wrapper">
-				<button id="todo-list-completed-delete-all-cancel" onclick="prplTodoWidget.closeDeleteAllPopover()">
+				<button id="todo-list-completed-delete-all-cancel">
 					<?php
 					/* translators: %1$s is the strong tag, %2$s is the closing strong tag. */
 					\printf( \esc_html__( '%1$sNo%2$s, keep this list', 'progress-planner' ), '<strong>', '</strong>' );
 					?>
 				</button>
-				<button id="todo-list-completed-delete-all-confirm" onclick="prplTodoWidget.deleteAllCompletedTasksAndClosePopover()">
+				<button id="todo-list-completed-delete-all-confirm">
 					<?php
 					/* translators: %1$s is the strong tag, %2$s is the closing strong tag. */
 					\printf( \esc_html__( '%1$sYes%2$s, delete all completed tasks', 'progress-planner' ), '<strong>', '</strong>' );

classes/class-suggested-tasks-db.php

@@ -375,7 +375,7 @@ public function get( $args = [] ) {
 					)
 				)
 			);
-			$results         = array_merge( $results, $results_trashed );
+			$results         = \array_merge( $results, $results_trashed );
 		}
 
 		\wp_cache_set( $cache_key, $results, static::GET_TASKS_CACHE_GROUP );

classes/class-suggested-tasks.php

@@ -609,6 +609,6 @@ function ( $task ) use ( $args ) {
 	 * @return string
 	 */
 	public function get_task_id_from_slug( $slug ) {
-		return explode( '__trashed', $slug )[0];
+		return \explode( '__trashed', $slug )[0];
 	}
 }

classes/suggested-tasks/providers/class-permalink-structure.php

@@ -266,7 +266,7 @@ public function handle_interactive_task_specific_submit() {
 			\wp_send_json_error( [ 'message' => \esc_html__( 'Missing value.', 'progress-planner' ) ] );
 		}
 
-		$permalink_structure = trim( \sanitize_text_field( \wp_unslash( $_POST['value'] ) ) );
+		$permalink_structure = \trim( \sanitize_text_field( \wp_unslash( $_POST['value'] ) ) );
 
 		if ( empty( $permalink_structure ) ) {
 			\wp_send_json_error( [ 'message' => \esc_html__( 'Invalid permalink structure.', 'progress-planner' ) ] );

classes/suggested-tasks/providers/class-remove-terms-without-posts.php

@@ -343,14 +343,14 @@ public function add_task_actions( $data = [], $actions = [] ) {
 
 		$actions[] = [
 			'priority' => 10,
-			'html'     => sprintf(
+			'html'     => \sprintf(
 				'<a href="#" class="prpl-tooltip-action-text prpl-delete-term-action" role="button"
 					data-task-context=\'%s\'
 					onclick="event.preventDefault(); document.getElementById(\'prpl-popover-%s\')?.showPopover(); this.dispatchEvent(new CustomEvent(\'prpl-interactive-task-action-remove-terms-without-posts\', { bubbles: true, detail: JSON.parse(this.dataset.taskContext) }));">
 					%s
 				</a>',
-				htmlspecialchars(
-					wp_json_encode(
+				\htmlspecialchars(
+					\wp_json_encode(
 						[
 							'post_title'       => $task_details['post_title'],
 							'target_term_id'   => $task_data['target_term_id'],