Improve accessibility of the AJAX search (aria-live, focus, loader)

loevgaard · loevgaard · commit a29ff3a8f4af · 2026-07-10T20:09:24.000+02:00
After every AJAX filter/sort/page change the whole #search-form node is swapped, which was a triple problem for assistive-technology users. - Wrap the hits count in a role=status aria-live=polite region so the updated "N results" is announced after each update. - Give the loader overlay role=status and a translated aria-label ("Loading results…", added to all 12 locales) so "loading" is conveyed. - In search.js #replaceContent(): record the active element's id/name before the swap and restore focus to the equivalent element afterwards, falling back to focusing the results region (tabindex=-1) so focus is never dumped back on <body>. Closes #133
diff --git a/src/Resources/public/js/search.js b/src/Resources/public/js/search.js
@@ -322,12 +322,54 @@ class SearchManager {
             return null;
         }
 
+        // Remember what was focused: replaceWith() removes the element the user just operated
+        // (a checkbox, the sort select), so focus would reset to <body> and keyboard users would
+        // have to tab from the top again after every interaction.
+        const active = document.activeElement;
+        const focusId = active instanceof Element ? active.id : '';
+        const focusName = (active instanceof HTMLInputElement || active instanceof HTMLSelectElement || active instanceof HTMLTextAreaElement) ? active.name : '';
+
         existingContent.replaceWith(newContent);
         this.#initializeForm();
 
+        this.#restoreFocus(newContent, focusId, focusName);
+
         return newContent;
     }
 
+    /**
+     * Restores focus to the equivalent element in the freshly swapped-in content: the same id, or
+     * the same field name, or — as a fallback — the results region itself (so focus is never left
+     * on <body>).
+     *
+     * @param {Element} container
+     * @param {string} focusId
+     * @param {string} focusName
+     */
+    #restoreFocus(container, focusId, focusName) {
+        let target = null;
+
+        if (focusId !== '') {
+            target = container.querySelector(`#${CSS.escape(focusId)}`) ?? document.getElementById(focusId);
+        }
+
+        if (target === null && focusName !== '') {
+            target = container.querySelector(`[name="${CSS.escape(focusName)}"]`);
+        }
+
+        if (target === null) {
+            // Fallback: move focus into the results region so it isn't dumped back at <body>.
+            target = container;
+            if (!container.hasAttribute('tabindex')) {
+                container.setAttribute('tabindex', '-1');
+            }
+        }
+
+        if (typeof target.focus === 'function') {
+            target.focus({ preventScroll: true });
+        }
+    }
+
     /**
      * Emits a bubbling `search:content-updated` event so other scripts can re-initialise
      * widgets after the results markup is swapped.
diff --git a/src/Resources/translations/messages.da.yaml b/src/Resources/translations/messages.da.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Indlæser resultater…'
             no_results:
                 body: 'Prøv at søge efter noget andet'
                 header: 'Ingen resultater fundet'
diff --git a/src/Resources/translations/messages.de.yaml b/src/Resources/translations/messages.de.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Ergebnisse werden geladen…'
             no_results:
                 body: 'Versuchen Sie, nach etwas anderem zu suchen'
                 header: 'Keine Ergebnisse gefunden'
diff --git a/src/Resources/translations/messages.en.yaml b/src/Resources/translations/messages.en.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Loading results…'
             no_results:
                 body: 'Try to search for something else'
                 header: 'No results found'
diff --git a/src/Resources/translations/messages.es.yaml b/src/Resources/translations/messages.es.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Cargando resultados…'
             no_results:
                 body: 'Intenta buscar otra cosa'
                 header: 'No se encontraron resultados'
diff --git a/src/Resources/translations/messages.fr.yaml b/src/Resources/translations/messages.fr.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Chargement des résultats…'
             no_results:
                 body: 'Essayez de rechercher autre chose'
                 header: 'Aucun résultat trouvé'
diff --git a/src/Resources/translations/messages.it.yaml b/src/Resources/translations/messages.it.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Caricamento dei risultati…'
             no_results:
                 body: 'Prova a cercare qualcos''altro'
                 header: 'Nessun risultato trovato'
diff --git a/src/Resources/translations/messages.lt.yaml b/src/Resources/translations/messages.lt.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Kraunami rezultatai…'
             no_results:
                 body: 'Pabandykite ieškoti ko nors kito'
                 header: 'Rezultatų nerasta'
diff --git a/src/Resources/translations/messages.nl.yaml b/src/Resources/translations/messages.nl.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Resultaten laden…'
             no_results:
                 body: 'Probeer iets anders te zoeken'
                 header: 'Geen resultaten gevonden'
diff --git a/src/Resources/translations/messages.no.yaml b/src/Resources/translations/messages.no.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Laster resultater…'
             no_results:
                 body: 'Prøv å søke etter noe annet'
                 header: 'Ingen resultater funnet'
diff --git a/src/Resources/translations/messages.pl.yaml b/src/Resources/translations/messages.pl.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Ładowanie wyników…'
             no_results:
                 body: 'Spróbuj wyszukać coś innego'
                 header: 'Nie znaleziono wyników'
diff --git a/src/Resources/translations/messages.ro.yaml b/src/Resources/translations/messages.ro.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Se încarcă rezultatele…'
             no_results:
                 body: 'Încearcă să cauți altceva'
                 header: 'Niciun rezultat găsit'
diff --git a/src/Resources/translations/messages.sv.yaml b/src/Resources/translations/messages.sv.yaml
@@ -8,6 +8,7 @@ setono_sylius_meilisearch:
                 price: Price
                 size: Size
                 taxons: Category
+            loading: 'Laddar resultat…'
             no_results:
                 body: 'Försök att söka efter något annat'
                 header: 'Inga resultat hittades'
diff --git a/src/Resources/views/loader.html.twig b/src/Resources/views/loader.html.twig
@@ -1,4 +1,4 @@
-<div id="ssm-overlay">
+<div id="ssm-overlay" role="status" aria-live="assertive" aria-label="{{ 'setono_sylius_meilisearch.form.search.loading'|trans }}">
     <div class="ssm-loader"></div>
 </div>
 <style>
diff --git a/src/Resources/views/search/_hits_count.html.twig b/src/Resources/views/search/_hits_count.html.twig
@@ -1,2 +1,5 @@
 {# @var searchResult \Setono\SyliusMeilisearchPlugin\Engine\SearchResult #}
-{{ 'setono_sylius_meilisearch.form.search.results_count'|trans({'%count%': searchResult.totalHits}) }}
+{# role=status + aria-live so screen readers announce the new result count after each AJAX update #}
+<span class="ssm-hits-count" role="status" aria-live="polite">
+    {{- 'setono_sylius_meilisearch.form.search.results_count'|trans({'%count%': searchResult.totalHits}) -}}
+</span>
diff --git a/tests/Application/e2e/search.spec.ts b/tests/Application/e2e/search.spec.ts
@@ -57,6 +57,22 @@ test.describe('shop search page', () => {
         await expect(names(page)).toHaveCount(1);
     });
 
+    test('announces the result count and restores focus after an AJAX swap', async ({ page }) => {
+        await page.goto('/en_US/search?q=jeans');
+
+        // The hits count is an aria-live region so screen readers announce updates
+        await expect(page.locator('.ssm-hits-count[role="status"][aria-live="polite"]')).toBeVisible();
+
+        const checkbox = page.locator('.ssm-filters input[name="f[brand][]"][value="Celsius Small"]');
+        await checkbox.focus();
+        await checkbox.check();
+        await expect(page).toHaveURL(/f%5Bbrand%5D%5B%5D=Celsius/);
+
+        // After the swap, focus is restored to the equivalent field (not lost to <body>)
+        const focusedName = await page.evaluate(() => document.activeElement?.getAttribute('name'));
+        expect(focusedName).toBe('f[brand][]');
+    });
+
     test.describe('without javascript', () => {
         test.use({ javaScriptEnabled: false });
 
