Merge pull request #367 from ember-a11y/melsumner/add-qp-support

Add support for queryParam flexibility

README.md

@@ -71,8 +71,8 @@ export default class ApplicationController extends Controller {
 
 The validator function:
 
-- Receives a [Transition](https://api.emberjs.com/ember/release/classes/Transition) object containing information about the source and destination routes
-- Should return `true` if refocusing should occur, otherwise `false`
+* Receives a [Transition](https://api.emberjs.com/ember/release/classes/Transition) object containing information about the source and destination routes
+* Should return `true` if refocusing should occur, otherwise `false`
 
 If you wish to extend the default behavior (rather than completely replacing it), you can import the default validator like so:
 
@@ -94,10 +94,13 @@ If you wish to extend the default behavior (rather than completely replacing it)
 Additional Options
 ------------------------------------------------------------------------------
 
-* `skipLink` - pass `{{false}}` if you do not want to implement a skip link.
-* `skipTo` - pass a specific element ID that should receive focus on skip.
-* `skipText` - customize the text passed in the skip link. Defaults to "Skip to main content".
-* `navigationText` - customize the text passed as the navigation message. Defaults to "The page navigation is complete. You may now navigate the page content as you wish."
+All of these are optional and have default values.
+
+* `skipLink` - pass `{{false}}` if you do not want to implement a bypass block/skip link.
+* `skipTo` - pass a specific element ID that should receive focus on skip. Defaults to `#main`.
+* `skipText` - customize the text passed in the skip link. Defaults to `Skip to main content`.
+* `navigationText` - customize the text passed as the navigation message. Defaults to `The page navigation is complete. You may now navigate the page content as you wish`.
+* `excludeAllQueryParams` - pass `{{true}}` if you want to exclude all query params from the route change check/focus management. Really shouldn't do this, but you might be upgrading an older app and need this for a little bit, or you are using QPs in a specific way and would like to otherwise benefit from the accessibility options in this addon. If you only need to exclude _some_ QPs, use the custom validator function instead.
 
 FastBoot
 ------------------------------------------------------------------------------

addon/components/navigation-narrator.js

@@ -64,19 +64,36 @@ export default class NavigationNarratorComponent extends Component {
   }
 
   /*
-   * @param includeQueryParams
+   * @param excludeAllQueryParams
    * @type {boolean}
    * @description Whether or not to include all query params in definition of a route transition. If you want to include/exclude _some_ query params, the routeChangeValidator function should be used instead.
-   * @default true
+   * @default false
+   */
+  get excludeAllQueryParams() {
+    return this.args.excludeAllQueryParams ?? false;
+  }
+
+  /*
+   * @param hasQueryParams
+   * @type {boolean}
+   * @description Detect if the `transition.from` or the `transition.to` has queryParams.
+   * @default false
    */
-  get includeQueryParams() {
-    return this.args.includeQueryParams ?? true;
+  get hasQueryParams() {
+    const qps =
+      (this.transition.from && this.transition.from.queryParams) ||
+      (this.transition.to && this.transition.to.queryParams);
+
+    if (qps && Object.keys(qps).length > 0) {
+      return true;
+    } else {
+      return false;
+    }
   }
 
   constructor() {
     super(...arguments);
 
-    // focus on the navigation message after render
     this.router.on('routeDidChange', this.onRouteChange);
 
     registerDestructor(this, () => {
@@ -88,8 +105,16 @@ export default class NavigationNarratorComponent extends Component {
 
   @action
   onRouteChange(transition) {
-    let shouldFocus = this.routeChangeValidator(transition);
+    let shouldFocus;
+    this.transition = transition; // We need to do this because we can't pass an argument to a getter
+
+    if (this.excludeAllQueryParams && this.hasQueryParams) {
+      return;
+    }
+
+    shouldFocus = this.routeChangeValidator(transition);
 
+    // leaving this here for now because maybe it needs to be used in a custom validator function
     if (!shouldFocus) {
       return;
     }

tests/dummy/app/styles/app.css

@@ -30,12 +30,12 @@ html {
 body {
   font-size: 1rem;
   line-height: 1.2;
-  font-family: Roboto, sans-serif;
+  font-family: system-ui, Roboto, sans-serif;
   padding: 0
 }
 
 main {
-  padding: .5rem 1rem;
+  padding: 0.5rem 1rem;
   min-height: 90vh;
 }
 
@@ -62,4 +62,10 @@ nav ul li a:hover {
 
 footer {
   padding: 0.5rem 1rem;
+  display: flex;
+  width: 100%;
+  justify-content: space-between;
+}
+footer a {
+  padding: 0.5rem;
 }

tests/dummy/app/templates/application.hbs

@@ -14,4 +14,5 @@
 </main>
 <footer>
   <p><a href="https://github.com/ember-a11y/ember-a11y-refocus">GitHub Repo</a></p>
+  <p><a href="/tests">Tests (for development)</a></p>
 </footer>

tests/dummy/config/environment.js

@@ -5,7 +5,7 @@ module.exports = function (environment) {
     modulePrefix: 'dummy',
     environment,
     rootURL: '/',
-    locationType: 'auto',
+    locationType: 'history',
     EmberENV: {
       FEATURES: {
         // Here you can enable experimental features on an ember canary build

tests/integration/components/navigation-narrator-test.js

@@ -2,7 +2,7 @@ import { module, test } from 'qunit';
 import { setupRenderingTest } from 'ember-qunit';
 import { render, clearRender, focus, blur, settled } from '@ember/test-helpers';
 import hbs from 'htmlbars-inline-precompile';
-import { MockTransition } from '../../helpers/mocks';
+import { MockTransition, MockRouteInfo } from '../../helpers/mocks';
 
 module('Integration | Component | navigation-narrator', function (hooks) {
   setupRenderingTest(hooks);
@@ -54,7 +54,7 @@ module('Integration | Component | navigation-narrator', function (hooks) {
       assert.dom('.ember-a11y-refocus-skip-link').hasText('Skip to content');
     });
 
-    test('it shows/hides for keyboard users', async function (assert) {
+    test('it shows/hides the bypass block/skip link for keyboard users', async function (assert) {
       await render(hbs`<NavigationNarrator />`);
 
       assert.dom('.ember-a11y-refocus-skip-link').doesNotHaveClass('active');
@@ -70,7 +70,7 @@ module('Integration | Component | navigation-narrator', function (hooks) {
   });
 
   module('on routeDidChange', function () {
-    test('it takes focus', async function (assert) {
+    test('it handles focus', async function (assert) {
       let router = this.owner.lookup('service:router');
 
       await render(hbs`<NavigationNarrator />`);
@@ -109,5 +109,69 @@ module('Integration | Component | navigation-narrator', function (hooks) {
 
       assert.dom('#ember-a11y-refocus-nav-message').isNotFocused();
     });
+
+    test('it transitions routes with query params and manages focus if `excludeAllQueryParams` is false (default)', async function (assert) {
+      let router = this.owner.lookup('service:router');
+
+      await render(hbs`<NavigationNarrator />`);
+
+      router.trigger(
+        'routeDidChange',
+        new MockTransition({
+          from: new MockRouteInfo({
+            name: 'biscuit',
+            params: { id: 'hobnob' },
+            queryParams: { region: 'amer' },
+          }),
+          to: new MockRouteInfo({
+            name: 'biscuit',
+            params: { id: 'hobnob' },
+            queryParams: { region: 'apac' },
+          }),
+        })
+      );
+
+      await settled();
+
+      assert.dom('#ember-a11y-refocus-nav-message').isFocused();
+    });
+
+    test('excludeAllQueryParams is true, queryParams exist, should not manage focus', async function (assert) {
+      let router = this.owner.lookup('service:router');
+
+      await render(hbs`<NavigationNarrator @excludeAllQueryParams={{true}} />`);
+
+      // router.trigger('routeDidChange', new MockTransition());
+      router.trigger(
+        'routeDidChange',
+        new MockTransition({
+          from: new MockRouteInfo({
+            name: 'biscuit',
+            params: { id: 'hobnob' },
+            queryParams: { region: 'amer' },
+          }),
+          to: new MockRouteInfo({
+            name: 'biscuit',
+            params: { id: 'hobnob' },
+            queryParams: { region: 'apac' },
+          }),
+        })
+      );
+
+      await settled();
+
+      assert.dom('#ember-a11y-refocus-nav-message').isNotFocused();
+    });
+
+    test('excludeAllQueryParams is true, but queryParams do not exist, manage focus', async function (assert) {
+      let router = this.owner.lookup('service:router');
+
+      await render(hbs`<NavigationNarrator @excludeAllQueryParams={{true}} />`);
+      router.trigger('routeDidChange', new MockTransition());
+
+      await settled();
+
+      assert.dom('#ember-a11y-refocus-nav-message').isFocused();
+    });
   });
 });