fix(wcag): Legend panel issues

* documentation: update accessibility best practices md file (work in progress)
* geolocator: add aria-disabled to clear filters button when no filters selected
* global: updates to use unique ids
* global styles: add css rule for aria-disabled icon buttons (buttonOutline)
* global styles: add reusable style utility for visuallyHidden
* legend layer: remove truncation from legend title
* legend layer: remove tooltips from non interactive elements (legend title)
* legend layer: add accessible code for loading layer
* legend panel: fix fullscreen icon button focus management
* legend panel: fix to allow both zoom icon buttons to retain focus after being pressed
* legend panel: improve aria and semantic HTML implementation
* legend panel: fix images that open a lightbox to use an interactive element (button)
* legend panel: fix focus management on lightbox close (returns focus to triggering item)
* legend panel fullscreen: update panel title to be more descriptive (read only)
* panel and other modals: improve aria and semantic HTML implementation
* panel and appBar and related: updated to use consistent ID naming conventions (mapId-containerType...)
* switch: make label required for accessibility
* switch: make focus indicators more noticeable
* switch: add unique id to associate the label to the switch

Author: kenchase

docs/app/accessibility.md

@@ -1,4 +1,4 @@
-## Accessibility
+# Accessibility
 
 _Work in progress_
 
@@ -17,3 +17,143 @@ https://mn.gov/mnit/about-mnit/accessibility/maps/
 https://microsoftedge.microsoft.com/addons/detail/axe-devtools-web-access/kcenlimkmjjkdfcaleembgmldmnnlfkn
 https://accessibilityinsights.io/downloads/
 https://github.com/dequelabs/axe-core
+
+Reference:
+https://www.w3.org/WAI/WCAG22/quickref/?currentsidebar=%23col_overview&versions=2.1&levels=aaa#consistent-navigation
+
+## Best Practices
+
+_Work in progress_
+
+### 1- Use unique and valid element IDs
+
+[update this once/if there's a helper function in place]
+
+Every element id in the DOM must be unique. Duplicate IDs break label-input associations (htmlFor), invalidate ARIA relationships (aria-labelledby, aria-describedby), and cause screen readers to behave unpredictably.
+
+- ensure ids are always unique
+- use kebab-case (as much as possible)
+- layer paths can generate invalid ids
+
+Suggested format (goes from least specific to most specific)
+
+```typescript
+// Start by prefixing ids with the following
+${mapId}-${containerType}-[element]
+${mapId}-${containerType}-${panel.panelId)-[element]
+
+// If a unique ID is required
+// uniqueId could be generated from:
+// const id = useId();
+// const id generateId(8);
+${mapId}-${containerType}-[element]-${uniqueId}
+${mapId}-${containerType}-${panel.panelId)-[element]-${uniqueId}
+
+```
+
+### 2- Use descriptive ARIA labels
+
+ARIA labels should clearly describe an element's purpose, not just its type or location. Generic labels like "button" or "link" are redundant since screen readers already announce the element's role — and repeating the same label across multiple elements (e.g., several "Learn more" buttons) leaves keyboard and screen reader users with no way to distinguish between them. Each label should convey enough context to make sense in isolation.
+
+```typescript
+
+// bad
+aria-label="Toggle visibility"
+
+// better
+aria-label="Toggle visibility - Confederation to 1914"
+```
+
+### 3- Use Semantic Elements for Interactions
+
+Clickable `<div>` and `<span>` elements are inaccessible by default — they receive no keyboard focus, emit no semantic role, and are invisible to assistive technologies. Native `<button>` and `<a>` elements come with built-in keyboard support, appropriate ARIA roles, and browser-managed focus behavior at no extra cost. In MUI, use Button, IconButton, and Link components over attaching onClick handlers to arbitrary elements.
+
+### 4- Use IconButton for buttons without labels
+
+The IconButton component in GeoView has built-in accessibility support through its implementation at ui/icon-button/icon-button.tsx:
+
+### 5- Validate HTML Output and WCAG level 2.1 AA
+
+From the browsers's developer tools, copy a section of generated code from a map, or a map component, and validate it
+
+- W3C.org validator
+- AI tool
+
+### 6- ARIA best practices
+
+- aria-pressed: Use aria-pressed rather than changing labels dynamically (can be confusing to screen readers
+- aria-controls:
+- ...
+
+### 7- Focus management: Do not use disabled on UI elements that get removed from the DOM
+
+Some UI elements should not be removed from the UI after they are pressed.
+
+- Use aria-disabled instead of disabled
+- Style the the aria-disabled element to look like it would if disabled
+
+### 8- Avoid removing buttons from the DOM
+
+- Causes focus management issues
+- Add example here
+
+### 9- Focus management: Restore focus when removing elements from the DOM
+
+- Add example here
+
+### 10- Handle esc key
+
+- Use “handleEscapeKey”
+
+### 11- Provide screen reader version of Loading indicators
+
+- Add code example here
+
+## Quick Testing Tips and Notes
+
+_Work in progress_
+
+### WCAG SC 1.4.4 - Resize text
+
+- Set browser zoom to 200%
+
+### WCAG SC 1.4.5 - Images of Text
+
+This does not include text that is part of a picture that contains significant other visual content. Examples of such pictures include graphs, screenshots, and diagrams which visually convey important information through more than just text.
+
+[Reference](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-text-presentation.html#:~:text=1.4.5%20Images%20of%20Text,to%20the%20information%20being%20conveyed.)
+
+### WCAG SC 1.4.10 - Reflow
+
+- Resize browser window to 1280 pixels wide and set zoom to 400%
+
+## Limitations
+
+_Work in progress_
+
+### 1 - Global
+
+English layer names embedded in French UI may lack lang="en" (and vice versa). This is often defensible:
+
+- Content owner's responsibility
+- Some technical data may not always have a translation and It wouldn't be feasible to detect the language or origin
+
+[Reference 1](https://laws.justice.gc.ca/eng/regulations/SOR-2021-241/nifnev.html)
+
+[Reference 2](https://www.canada.ca/en/employment-social-development/programs/accessible-canada/regulations-summary-act/amendment.html)
+
+#### 3.1.2 - Language of Parts
+
+### 2 - Legend Panel
+
+#### WCAG SC 1.1.1 Non-text Content — Known limitation
+
+See SC 1.3.1 — Known limitation. Fixing that issue would resolve this limitation as well.
+
+#### WCAG SC 1.3.1 Info and Relationships — Known limitation
+
+The legend symbol images cannot be programmatically described at this time. The visual relationship between each symbol's appearance and its map class (e.g. colour, size, shape encoding magnitude) is not available to AT users.
+
+**What this means for users in practice** — AT users are not blocked from operating the legend (they can show/hide classes by name), but they cannot independently interpret what the map symbols look like. This is a partial conformance gap rather than a complete barrier to use.
+
+**What would unblock the fix** — if the symbology data driving each legend image is available in the layer configuration (e.g. colour hex, symbol type, size range), those values could be used to auto-generate sr-only descriptions programmatically without manual authoring per symbol. That might be worth investigating as a future enhancement.

packages/geoview-core/public/locales/en/translation.json

@@ -20,14 +20,15 @@
     "guide": "Guide",
     "fullScreen": "Full screen",
     "processing": "Processing __param__ element(s) of __param__",
-    "overview": "Overview",
     "clickEnlarge": "Click to enlarge",
     "show": "Show",
     "hide": "Hide",
+    "toggle": "Toggle",
     "none": "No",
     "clearSearch": "Clear search",
     "enable": "Enable",
-    "disable": "Disable"
+    "disable": "Disable",
+    "panelLabel": "{{title}} panel"
   },
   "mapnav": {
     "arianavbar": "Vertical button group for map navigation",
@@ -105,6 +106,7 @@
   },
   "legend": {
     "title": "Legend",
+    "titleFullScreen": "Legend - Overview (read only)",
     "removeLayer": "Remove layer",
     "zoomTo": "Zoom to layer",
     "addLayer": "Add a layer",
@@ -119,7 +121,11 @@
     "legendInstructions": "Legend Instructions",
     "noLayersAdded": "No layers added to the map",
     "noLayersAddedDescription": "Add layers to the map by clicking on the 'Layers' button and adding the layers you want to display.",
-    "selectLayerAndScroll": "Show in Layers panel"
+    "selectLayerAndScroll": "Show in Layers panel",
+    "layerLoadingDescriptive": "Loading layer {{layerName}}",
+    "layerLoadedDescriptive": "Layer {{layerName}} loaded successfully",
+    "layerErrorDescriptive": "Error loading layer {{layerName}}",
+    "layerOutOfRangeScreenReader": "(visibility limited by scale)"
   },
   "layers": {
     "title": "Layers",

packages/geoview-core/public/locales/fr/translation.json

@@ -17,17 +17,18 @@
     "openFullscreen": "Ouvrir en plein écran",
     "closeFullscreen": "Fermer le plein écran",
     "openGuide": "Ouvrir le guide",
-    "overview": "Aperçu",
     "guide": "Guide",
     "fullScreen": "Plein écran",
     "processing": "Traitement de __param__ element(s) sur __param__",
     "clickEnlarge": "Cliquer pour agrandir",
     "show": "Afficher",
     "hide": "Masquer",
+    "toggle": "Basculer",
     "none": "Aucun",
     "clearSearch": "Effacer la recherche",
     "enable": "Activer",
-    "disable": "Désactiver"
+    "disable": "Désactiver",
+    "panelLabel": "Panneau de {{title}}"
   },
   "mapnav": {
     "arianavbar": "Groupe de buttons vertical pour navigation sur la carte",
@@ -105,6 +106,7 @@
   },
   "legend": {
     "title": "Légende",
+    "titleFullScreen": "Légende - Aperçu (en lecture seule)",
     "removeLayer": "Retirer la couche",
     "zoomTo": "Zoom sur la couche",
     "addLayer": "Ajouter une couche",
@@ -119,7 +121,11 @@
     "legendInstructions": "Legend Instructions",
     "noLayersAdded": "Aucune couche ajoutée",
     "noLayersAddedDescription": "Ajoutez des couches à la carte en cliquant sur le bouton 'Couches' et en sélectionnant les couches que vous souhaitez afficher.",
-    "selectLayerAndScroll": "Voir dans le panneau Couches"
+    "selectLayerAndScroll": "Voir dans le panneau Couches",
+    "layerLoadingDescriptive": "Chargement de la couche {{layerName}}",
+    "layerLoadedDescriptive": "La couche {{layerName}} a été chargée avec succès",
+    "layerErrorDescriptive": "Erreur lors du chargement de la couche {{layerName}}",
+    "layerOutOfRangeScreenReader": "(visibilité limitée par l'échelle)"
   },
   "layers": {
     "title": "Couches",

packages/geoview-core/src/core/components/app-bar/app-bar-helper.ts

@@ -1,8 +1,10 @@
 import type { Dispatch, SetStateAction } from 'react';
+
 import type { TypeButtonPanel } from '@/ui/panel/panel-types';
-import type { ButtonPanelType } from './app-bar';
 import { CONTAINER_TYPE } from '@/core/utils/constant';
 
+import type { ButtonPanelType } from './app-bar';
+
 export const helpOpenClosePanelByIdState = (
   buttonId: string,
   setterCallback: Dispatch<SetStateAction<ButtonPanelType>>,

packages/geoview-core/src/core/components/app-bar/app-bar.tsx

@@ -21,6 +21,7 @@ import type { TypeButtonPanel, TypePanelProps } from '@/ui/panel/panel-types';
 import ExportButton from '@/core/components/export/export-modal-button';
 import {
   useUIActiveFocusItem,
+  useUIActiveTrapGeoView,
   useUIAppbarComponents,
   useUIActiveAppBarTab,
   useUIHiddenTabs,
@@ -38,7 +39,7 @@ import Version from './buttons/version';
 import Share from './buttons/share';
 import { getSxClasses } from './app-bar-style';
 import { enforceArrayOrder, helpClosePanelById, helpOpenPanelById } from './app-bar-helper';
-import { CONTAINER_TYPE, TIMEOUT } from '@/core/utils/constant';
+import { CONTAINER_TYPE, LIGHTBOX_SELECTORS, TIMEOUT } from '@/core/utils/constant';
 import type { TypeValidAppBarCoreProps } from '@/api/types/map-schema-types';
 import { DEFAULT_APPBAR_CORE, DEFAULT_APPBAR_TABS_ORDER } from '@/api/types/map-schema-types';
 import { camelCase, handleEscapeKey } from '@/core/utils/utilities';
@@ -85,6 +86,7 @@ export function AppBar(props: AppBarProps): JSX.Element {
   const { tabId, isOpen, isFocusTrapped } = useUIActiveAppBarTab();
   const hiddenTabs = useUIHiddenTabs();
   const { hideClickMarker } = useMapStoreActions();
+  const activeTrapGeoView = useUIActiveTrapGeoView();
 
   const geoviewElement = useAppGeoviewHTMLElement().querySelector('[id^="mapTargetElement-"]') as HTMLElement;
 
@@ -363,15 +365,25 @@ export function AppBar(props: AppBarProps): JSX.Element {
       .map((panelName: string) => {
         // Get the button panel configuration for this panel name
         const buttonPanel = buttonPanels[panelName];
+
         // Only render if the button is explicitly set to visible
         if (buttonPanel?.button.visible !== undefined && buttonPanel?.button.visible) {
+          // WCAG - Compute ARIA attributes before rendering
+          const isPanelOpen: boolean = tabId === buttonPanel.button.id && isOpen;
+          const expandedState: 'true' | 'false' = isPanelOpen ? 'true' : 'false';
+          const ariaControls: string | undefined = activeTrapGeoView ? undefined : getButtonElementId(buttonPanel.button.id!, '-panel');
+          const ariaExpanded: 'true' | 'false' | undefined = activeTrapGeoView ? undefined : expandedState;
+
           return (
             <ListItem key={buttonPanel.button.id}>
               <IconButton
                 id={getButtonElementId(buttonPanel.button.id!, '-panel-btn')}
-                aria-controls={getButtonElementId(buttonPanel.button.id!, '-panel')}
                 aria-label={t(buttonPanel.button['aria-label'])}
-                aria-expanded={tabId === buttonPanel.button.id && isOpen ? 'true' : 'false'}
+                // In WCAG mode, panels are treated as dialogs because they are focus-trapped, so we set aria-haspopup to dialog to indicate that.
+                aria-haspopup={activeTrapGeoView ? 'dialog' : undefined}
+                // In default mode, panels are treated as regions, so we use aria-controls and aria-expanded to indicate the relationship and state.
+                aria-controls={ariaControls}
+                aria-expanded={ariaExpanded}
                 tooltipPlacement="right"
                 className={`buttonFilled ${tabId === buttonPanel.button.id && isOpen ? 'active' : ''}`}
                 size="small"
@@ -408,8 +420,6 @@ export function AppBar(props: AppBarProps): JSX.Element {
               <ListItem>
                 <ExportButton
                   id={`${mapId}-${CONTAINER_TYPE.APP_BAR}-export-modal-btn`}
-                  ariaControls={`${mapId}-export-modal`}
-                  ariaExpanded={activeModalId === DEFAULT_APPBAR_CORE.EXPORT}
                   className={` buttonFilled ${activeModalId === DEFAULT_APPBAR_CORE.EXPORT ? 'active' : ''}`}
                 />
               </ListItem>
@@ -439,11 +449,18 @@ export function AppBar(props: AppBarProps): JSX.Element {
               button={buttonPanel.button}
               onOpen={buttonPanel.onOpen}
               onClose={hideClickMarker}
-              onKeyDown={(event: KeyboardEvent) =>
+              onKeyDown={(event: KeyboardEvent) => {
+                // Early exit if lightbox is handling ESC
+                if (event.key === 'Escape') {
+                  const isLightboxOpen = document.querySelector(LIGHTBOX_SELECTORS.ROOT) !== null;
+                  if (isLightboxOpen) {
+                    return;
+                  }
+                }
                 handleEscapeKey(event.key, getButtonElementId(buttonPanel.button?.id ?? '', '-panel-btn'), isFocusTrapped, () => {
                   setActiveAppBarTab(buttonPanel.button?.id ?? '', false, false);
-                })
-              }
+                });
+              }}
               onGeneralClose={() => {
                 handleGeneralCloseClicked(buttonPanel.button?.id ?? '');
               }}