@ohos-ports/ember-a11y-refocus 5.2.1-beta.1

package/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2021
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# ember-a11y-refocus
+
+[![Latest NPM release](https://img.shields.io/npm/v/ember-a11y-refocus.svg)](https://www.npmjs.com/package/ember-a11y-refocus)
+[![Ember Observer Score](https://emberobserver.com/badges/ember-a11y-refocus.svg)](http://emberobserver.com/addons/ember-a11y-refocus)
+[![Publish Stable](https://github.com/ember-a11y/ember-a11y-refocus/actions/workflows/publish.yml/badge.svg)](https://github.com/ember-a11y/ember-a11y-refocus/actions/workflows/publish.yml)
+
+## What This Addon Does
+
+In order to provide a mechanism for Ember applications to meet certain WCAG Success Criteria, this addon does three things:
+
+1. Transition message: it adds a message to the page to let the screen reader user know that the route has changed.
+2. Transition focus management: it moves the focus to that message for the screen reader user, effectively resetting focus in Ember apps (similar to how a native web page/site works).
+3. Skip link: It provides a bypass mechanism so the user can skip to the page's primary content (see <https://www.w3.org/TR/WCAG20-TECHS/G1.html>).
+
+There are quite a few options, and many things are customizable.
+Make sure to read the whole README file to fully understand how to use this addon!
+
+## Why This Addon is Needed
+
+Single-Page Applications(SPAs) use `pushState` to allow portions of the page to be updated or replaced without a whole new page being rendered. While this was a positive gain for performance on the web, it has made an entire type of web app not accessible (usable) for folks who depend on assistive technology(such as screen-readers) to use the web. With the prolific rise of JavaScript frameworks as the tool of choice for building modern web applications, screen-reader users have become increasingly left out of many experiences of the modern web that have become necessary for everyday life, such as online banking, paying bills, and ordering products and services.
+
+Since `pushState` does nothing to inform the browser--and, by extent, the screen reader--that new content is present, the screen-reader user has no way of knowing that new content exists, or that navigation to a new page was successful. Additionally, focus remains where it was, instead of being reset in a predictable fashion.
+
+## Installation
+
+```bash
+pnpm add ember-a11y-refocus
+```
+
+Or with npm:
+
+```bash
+npm install ember-a11y-refocus
+```
+
+## Usage
+
+- Insert `<NavigationNarrator/>` into your application.hbs file, inside of the `<header>` element.
+- Next, add `id="main"` to the primary content element in your application (should be the `<main>` element).
+
+Example:
+
+```html
+<header>
+  <NavigationNarrator/>
+  <!-- other header content-->
+</header>
+<main id="main">
+ <!--main content-->
+</main>
+```
+
+Gjs/Gts:
+
+- Import the `NavigationNarrator` 
+- Insert `<NavigationNarrator/>` component into your template file, inside of the `<header>` element.
+- Next, add `id="main"` to the primary content element in your application (should be the `<main>` element).
+
+Example:
+
+```gjs
+import { NavigationNarrator } from 'ember-a11y-refocus';
+
+<template>
+  <header>
+    <NavigationNarrator/>
+    <!-- other header content-->
+  </header>
+  <main id="main">
+   <!--main content-->
+  </main>
+</template>
+```
+
+Template Registry is available for loose mode users:
+
+```ts
+import type EmberA11yRefocusRegistry from 'ember-a11y-refocus/template-registry';
+
+declare module '@glint/environment-ember-loose/registry' {
+  export default interface Registry
+    extends EmberA11yRefocusRegistry {}
+}
+```
+
+Minimal CSS is provided to style the skip link and navigation message.
+
+```diff
+/* app/app.ts */
++ import 'ember-a11y-refocus/styles/navigation-narrator.css';
++
+import Application from '@ember/application';
+import loadInitializers from 'ember-load-initializers';
+import Resolver from 'ember-resolver';
+
+import config from './config/environment';
+
+export default class App extends Application {
+  modulePrefix = config.modulePrefix;
+  podModulePrefix = config.podModulePrefix;
+  Resolver = Resolver;
+}
+
+loadInitializers(App, config.modulePrefix);
+```
+
+<details>
+
+<summary>Use Sass?</summary>
+
+If your build tool resolves node module paths (e.g. Vite), the full specifier works directly:
+
+```scss
+/* app/styles/app.scss */
+@use "ember-a11y-refocus/styles/navigation-narrator.css";
+```
+
+For classic Ember apps using `ember-cli-sass`, add the path to `includePaths`:
+
+```js
+// ember-cli-build.js
+const app = new EmberApp(defaults, {
+  sassOptions: {
+    includePaths: ['node_modules/ember-a11y-refocus/dist/styles'],
+  },
+});
+```
+
+Then import with the short path:
+
+```scss
+/* app/styles/app.scss */
+@use "navigation-narrator.css";
+```
+
+</details>
+
+### Feature: Customizing the definition of a route change
+
+This addon provides support for custom definitions of which route changes should trigger refocusing behavior.
+To use this functionality, pass `routeChangeValidator` when you invoke the component, and add your custom action in the appropriate controller (likely the application controller).
+
+So when you add the component to your application template:
+
+```hbs
+<NavigationNarrator @routeChangeValidator={{this.myCustomValidator}} />
+```
+
+This is what the controller could look like:
+
+```js
+import Controller from '@ember/controller';
+
+export default class ApplicationController extends Controller {
+  myCustomValidator(transition) {
+    // Custom logic goes here...
+  }
+}
+```
+
+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`
+
+**Note:** If you wish to extend the default behavior (rather than completely replacing it), you can import the default validator like so:
+
+```js
+ import Controller from '@ember/controller';
+ import { defaultValidator } from 'ember-a11y-refocus';
+
+ export default class ApplicationController extends Controller {
+   myCustomValidator(transition) {
+     if (transition.from.name === 'special') { // this if statement is where you'd put your custom route validation
+        return false;
+     } else { // include this to get the defaultValidator as a fallback
+        return defaultValidator(transition);
+     }
+   }
+ }
+ ```
+
+## Additional Options
+
+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](https://github.com/ember-a11y/ember-a11y-refocus?tab=readme-ov-file#customizing-the-definition-of-a-route-change) instead.
+
+## FastBoot
+
+With FastBoot, you'll want to guard the `<NavigationNarrator />` from rendering. Like so:
+
+```hbs
+{{#unless this.fastboot.isFastBoot}}
+  <NavigationNarrator />
+{{/unless}}
+```
+
+Where `this.fastboot` is the fastboot service injected in the application controller.
+
+## FAQs
+
+### What about async data loading?
+
+Async data can be loaded as it normally would be. Since this addon does not use `aria-live`, it won't interfere with or compete with other loading states. This will only give the user with a screen reader a message that the route (URL) has changed, and place the focus where they expect it to be (reset to the top left of the page).
+
+### What if I want to put focus somewhere specific in the app flow?
+
+Since this will run before other content, focus can be programmatically moved by the developer to go somewhere else. The message should still read out, and is findable by users with screen readers.
+
+## Compatibility
+
+- Ember.js v4.12 or above
+- Node.js v22 or above
+
+## Contributing
+
+Contributions are welcome.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE.md).

package/addon-main.cjs

@@ -0,0 +1,5 @@
+'use strict';
+
+const { addonV1Shim } = require('@embroider/addon-shim');
+
+module.exports = addonV1Shim(__dirname);

package/declarations/components/navigation-narrator.d.ts

@@ -0,0 +1,61 @@
+import Component from '@glimmer/component';
+import type RouterService from '@ember/routing/router-service';
+import type Owner from '@ember/owner';
+import type Transition from '@ember/routing/transition';
+import type { Timer } from '@ember/runloop';
+export interface NavigationNarratorSignature {
+    Args: {
+        /** Whether to include the skip link. Defaults to `true`. */
+        skipLink?: boolean;
+        /** CSS selector the skip link jumps to. Defaults to `'#main'`. */
+        skipTo?: string;
+        /** Text content of the skip link. Defaults to `'Skip to main content'`. */
+        skipText?: string;
+        /** Text announced by a screen reader after navigation. */
+        navigationText?: string;
+        /** Custom logic for determining whether a transition should trigger narration. */
+        routeChangeValidator?: (transition: Transition) => boolean;
+        /** Whether to ignore query param changes during route comparisons. Defaults to `false`. */
+        excludeAllQueryParams?: boolean;
+    };
+    Element: HTMLElement;
+}
+/**
+ * 🎧 NavigationNarrator
+ *
+ * Announces route changes for screen readers using a visually-hidden element,
+ * and optionally renders a "Skip to main content" link.
+ *
+ * Usage:
+ * ```gjs
+ * import { NavigationNarrator } from 'ember-a11y-refocus';
+ *
+ * <template>
+ *   <NavigationNarrator />
+ * </template>
+ * ```
+ */
+export default class NavigationNarrator extends Component<NavigationNarratorSignature> {
+    readonly router: RouterService;
+    isSkipLinkFocused: boolean;
+    timer: Timer | undefined;
+    transition: Transition | undefined;
+    constructor(owner: Owner, args: NavigationNarratorSignature['Args']);
+    /** Whether to include the skip link. Defaults to `true`. */
+    get skipLink(): boolean;
+    /** Selector for the skip link target. Defaults to `'#main'`. */
+    get skipTo(): string;
+    /** Text for the skip link. Defaults to `'Skip to main content'`. */
+    get skipText(): string;
+    /** Text announced by screen readers after route transition. */
+    get navigationText(): string;
+    /** Validator function for transitions. */
+    get routeChangeValidator(): (transition: Transition) => boolean;
+    /** Whether to ignore query param changes. Defaults to `false`. */
+    get excludeAllQueryParams(): boolean;
+    /** Whether the current transition includes query param changes. */
+    get hasQueryParams(): boolean;
+    onRouteChange: (transition: Transition) => void;
+    handleSkipLinkFocus: () => void;
+}
+//# sourceMappingURL=navigation-narrator.d.ts.map

package/declarations/components/navigation-narrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-narrator.d.ts","sourceRoot":"","sources":["../../src/components/navigation-narrator.gts"],"names":[],"mappings":"AA+KA,OAAO,SAAS,MAAM,oBAAoB,CAAC;AAS3C,OAAO,KAAK,aAAa,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,UAAU,MAAM,2BAA2B,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE;QACJ,4DAA4D;QAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;QAEnB,kEAAkE;QAClE,MAAM,CAAC,EAAE,MAAM,CAAC;QAEhB,2EAA2E;QAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;QAElB,0DAA0D;QAC1D,cAAc,CAAC,EAAE,MAAM,CAAC;QAExB,kFAAkF;QAClF,oBAAoB,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC;QAE3D,2FAA2F;QAC3F,qBAAqB,CAAC,EAAE,OAAO,CAAC;KACjC,CAAC;IAEF,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,OAAO,OAAO,kBAAmB,SAAQ,SAAS,CAAC,2BAA2B,CAAC;IACpF,SAA0B,MAAM,EAAE,aAAa,CAAC;IAEvC,iBAAiB,UAAS;IAEnC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IACzB,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;gBAEvB,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,2BAA2B,CAAC,MAAM,CAAC;IAanE,4DAA4D;IAC5D,IAAI,QAAQ,YAEX;IAED,gEAAgE;IAChE,IAAI,MAAM,WAET;IAED,oEAAoE;IACpE,IAAI,QAAQ,WAEX;IAED,+DAA+D;IAC/D,IAAI,cAAc,WAKjB;IAED,0CAA0C;IAC1C,IAAI,oBAAoB,iBArEc,UAAU,KAAK,OAAO,CAuE3D;IAED,kEAAkE;IAClE,IAAI,qBAAqB,YAExB;IAED,mEAAmE;IACnE,IAAI,cAAc,YASjB;IAED,aAAa,GAAI,YAAY,UAAU,UA2BrC;IAEF,mBAAmB,aAEjB;CAmCH"}

package/declarations/index.d.ts

@@ -0,0 +1,3 @@
+export { default as NavigationNarrator } from './components/navigation-narrator';
+export { defaultValidator } from './utils/validators.ts';
+//# sourceMappingURL=index.d.ts.map

package/declarations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AACrF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/declarations/template-registry.d.ts

@@ -0,0 +1,5 @@
+import type NavigationNarrator from './components/navigation-narrator';
+export default interface EmberA11yRefocusRegistry {
+    NavigationNarrator: typeof NavigationNarrator;
+}
+//# sourceMappingURL=template-registry.d.ts.map

package/declarations/template-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-registry.d.ts","sourceRoot":"","sources":["../src/template-registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,kBAAkB,MAAM,sCAAsC,CAAC;AAE3E,MAAM,CAAC,OAAO,WAAW,wBAAwB;IAC/C,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;CAC/C"}

package/declarations/utils/routing.d.ts

@@ -0,0 +1,13 @@
+import type RouteInfo from '@ember/routing/route-info';
+export interface RouteInfoLike {
+    name: string;
+    params: Record<string, unknown>;
+    queryParams: Record<string, unknown>;
+    parent: RouteInfoLike | RouteInfo | null;
+}
+/**
+ * Returns true if the given RouteInfo objects represent the same route in the
+ * tree, with matching params and query params.
+ */
+export declare function routeInfoEqual(a: RouteInfoLike | RouteInfo | null | undefined | void, b: RouteInfoLike | RouteInfo | null | undefined | void): boolean;
+//# sourceMappingURL=routing.d.ts.map

package/declarations/utils/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/utils/routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,2BAA2B,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,EACtD,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,GACrD,OAAO,CAoCT"}

package/declarations/utils/validators.d.ts

@@ -0,0 +1,9 @@
+import type RouteInfo from '@ember/routing/route-info';
+import type { RouteInfoLike } from './routing.ts';
+interface TransitionLike {
+    from?: RouteInfoLike | RouteInfo | null | undefined | void;
+    to?: RouteInfoLike | RouteInfo | null | undefined | void;
+}
+export declare function defaultValidator(transition: TransitionLike): boolean;
+export {};
+//# sourceMappingURL=validators.d.ts.map

package/declarations/utils/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/utils/validators.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,SAAS,MAAM,2BAA2B,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC;IAC3D,EAAE,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC;CAC1D;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,GAAG,OAAO,CAEpE"}

package/dist/_app_/components/navigation-narrator.js

@@ -0,0 +1 @@
+export { default } from "ember-a11y-refocus/components/navigation-narrator";

package/dist/components/navigation-narrator.js

@@ -0,0 +1,114 @@
+import Component from '@glimmer/component';
+import { service } from '@ember/service';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { registerDestructor } from '@ember/destroyable';
+import { cancel, schedule } from '@ember/runloop';
+import { defaultValidator } from '../utils/validators.js';
+import { precompileTemplate } from '@ember/template-compilation';
+import { setComponentTemplate } from '@ember/component';
+import { g, i } from 'decorator-transforms/runtime-esm';
+
+/**
+ * 🎧 NavigationNarrator
+ *
+ * Announces route changes for screen readers using a visually-hidden element,
+ * and optionally renders a "Skip to main content" link.
+ *
+ * Usage:
+ * ```gjs
+ * import { NavigationNarrator } from 'ember-a11y-refocus';
+ *
+ * <template>
+ *   <NavigationNarrator />
+ * </template>
+ * ```
+ */
+class NavigationNarrator extends Component {
+  static {
+    g(this.prototype, "router", [service]);
+  }
+  #router = (i(this, "router"), void 0);
+  static {
+    g(this.prototype, "isSkipLinkFocused", [tracked], function () {
+      return false;
+    });
+  }
+  #isSkipLinkFocused = (i(this, "isSkipLinkFocused"), void 0);
+  timer;
+  transition;
+  constructor(owner, args) {
+    super(owner, args);
+    this.router.on('routeDidChange', this.onRouteChange);
+    registerDestructor(this, () => {
+      // eslint-disable-next-line ember/no-runloop
+      cancel(this.timer);
+      this.timer = undefined;
+      this.router.off('routeDidChange', this.onRouteChange);
+    });
+  }
+  /** Whether to include the skip link. Defaults to `true`. */
+  get skipLink() {
+    return this.args.skipLink ?? true;
+  }
+  /** Selector for the skip link target. Defaults to `'#main'`. */
+  get skipTo() {
+    return this.args.skipTo ?? '#main';
+  }
+  /** Text for the skip link. Defaults to `'Skip to main content'`. */
+  get skipText() {
+    return this.args.skipText ?? 'Skip to main content';
+  }
+  /** Text announced by screen readers after route transition. */
+  get navigationText() {
+    return this.args.navigationText ?? 'The page navigation is complete. You may now navigate the page content as you wish.';
+  }
+  /** Validator function for transitions. */
+  get routeChangeValidator() {
+    return this.args.routeChangeValidator ?? defaultValidator;
+  }
+  /** Whether to ignore query param changes. Defaults to `false`. */
+  get excludeAllQueryParams() {
+    return this.args.excludeAllQueryParams ?? false;
+  }
+  /** Whether the current transition includes query param changes. */
+  get hasQueryParams() {
+    if (Object.keys(this.transition?.from?.queryParams || {}).length || Object.keys(this.transition?.to?.queryParams || {}).length > 0) {
+      return true;
+    } else {
+      return false;
+    }
+  }
+  onRouteChange = transition => {
+    this.transition = transition; // We need to do this because we can't pass an argument to a getter
+    // add a check to see if it's the same route
+    const hasSameRoute = this.transition.from?.name === this.transition.to?.name;
+    if (this.excludeAllQueryParams && this.hasQueryParams && hasSameRoute) {
+      return;
+    }
+    const shouldFocus = this.routeChangeValidator(transition);
+    // leaving this here for now because maybe it needs to be used in a custom validator function
+    if (!shouldFocus) {
+      return;
+    }
+    // eslint-disable-next-line ember/no-runloop
+    this.timer = schedule('afterRender', this, function () {
+      this.timer = undefined;
+      document.body.querySelector('#ember-a11y-refocus-nav-message')?.focus();
+    });
+  };
+  handleSkipLinkFocus = () => {
+    this.isSkipLinkFocused = !this.isSkipLinkFocused;
+  };
+  static {
+    setComponentTemplate(precompileTemplate("<div tabindex=\"-1\" id=\"ember-a11y-refocus-nav-message\" class=\"ember-sr-only ember-sr-only-focusable\">\n  {{this.navigationText}}\n</div>\n\n{{#if this.skipLink}}\n  <a href={{this.skipTo}} id=\"ember-a11y-refocus-skip-link\" class=\"ember-a11y-refocus-skip-link\n      {{if this.isSkipLinkFocused \"active\"}}\" {{on \"focus\" this.handleSkipLinkFocus}} {{on \"blur\" this.handleSkipLinkFocus}}>\n    {{this.skipText}}\n  </a>\n{{/if}}", {
+      strictMode: true,
+      scope: () => ({
+        on
+      })
+    }), this);
+  }
+}
+
+export { NavigationNarrator as default };
+//# sourceMappingURL=navigation-narrator.js.map

package/dist/components/navigation-narrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-narrator.js","sources":["../../src/components/navigation-narrator.gts"],"sourcesContent":["import Component from '@glimmer/component';\nimport { service } from '@ember/service';\nimport { tracked } from '@glimmer/tracking';\nimport { on } from '@ember/modifier';\nimport { registerDestructor } from '@ember/destroyable';\nimport { schedule, cancel } from '@ember/runloop';\n\nimport { defaultValidator } from '../utils/validators.ts';\n\nimport type RouterService from '@ember/routing/router-service';\nimport type Owner from '@ember/owner';\nimport type Transition from '@ember/routing/transition';\nimport type { Timer } from '@ember/runloop';\n\nexport interface NavigationNarratorSignature {\n  Args: {\n    /** Whether to include the skip link. Defaults to `true`. */\n    skipLink?: boolean;\n\n    /** CSS selector the skip link jumps to. Defaults to `'#main'`. */\n    skipTo?: string;\n\n    /** Text content of the skip link. Defaults to `'Skip to main content'`. */\n    skipText?: string;\n\n    /** Text announced by a screen reader after navigation. */\n    navigationText?: string;\n\n    /** Custom logic for determining whether a transition should trigger narration. */\n    routeChangeValidator?: (transition: Transition) => boolean;\n\n    /** Whether to ignore query param changes during route comparisons. Defaults to `false`. */\n    excludeAllQueryParams?: boolean;\n  };\n\n  Element: HTMLElement;\n}\n\n/**\n * 🎧 NavigationNarrator\n *\n * Announces route changes for screen readers using a visually-hidden element,\n * and optionally renders a \"Skip to main content\" link.\n *\n * Usage:\n * ```gjs\n * import { NavigationNarrator } from 'ember-a11y-refocus';\n *\n * <template>\n *   <NavigationNarrator />\n * </template>\n * ```\n */\nexport default class NavigationNarrator extends Component<NavigationNarratorSignature> {\n  @service declare readonly router: RouterService;\n\n  @tracked isSkipLinkFocused = false;\n\n  timer: Timer | undefined;\n  transition: Transition | undefined;\n\n  constructor(owner: Owner, args: NavigationNarratorSignature['Args']) {\n    super(owner, args);\n\n    this.router.on('routeDidChange', this.onRouteChange);\n\n    registerDestructor(this, () => {\n      // eslint-disable-next-line ember/no-runloop\n      cancel(this.timer);\n      this.timer = undefined;\n      this.router.off('routeDidChange', this.onRouteChange);\n    });\n  }\n\n  /** Whether to include the skip link. Defaults to `true`. */\n  get skipLink() {\n    return this.args.skipLink ?? true;\n  }\n\n  /** Selector for the skip link target. Defaults to `'#main'`. */\n  get skipTo() {\n    return this.args.skipTo ?? '#main';\n  }\n\n  /** Text for the skip link. Defaults to `'Skip to main content'`. */\n  get skipText() {\n    return this.args.skipText ?? 'Skip to main content';\n  }\n\n  /** Text announced by screen readers after route transition. */\n  get navigationText() {\n    return (\n      this.args.navigationText ??\n      'The page navigation is complete. You may now navigate the page content as you wish.'\n    );\n  }\n\n  /** Validator function for transitions. */\n  get routeChangeValidator() {\n    return this.args.routeChangeValidator ?? defaultValidator;\n  }\n\n  /** Whether to ignore query param changes. Defaults to `false`. */\n  get excludeAllQueryParams() {\n    return this.args.excludeAllQueryParams ?? false;\n  }\n\n  /** Whether the current transition includes query param changes. */\n  get hasQueryParams() {\n    if (\n      Object.keys(this.transition?.from?.queryParams || {}).length ||\n      Object.keys(this.transition?.to?.queryParams || {}).length > 0\n    ) {\n      return true;\n    } else {\n      return false;\n    }\n  }\n\n  onRouteChange = (transition: Transition) => {\n    this.transition = transition; // We need to do this because we can't pass an argument to a getter\n\n    // add a check to see if it's the same route\n    const hasSameRoute =\n      this.transition.from?.name === this.transition.to?.name;\n\n    if (this.excludeAllQueryParams && this.hasQueryParams && hasSameRoute) {\n      return;\n    }\n\n    const shouldFocus = this.routeChangeValidator(transition);\n\n    // leaving this here for now because maybe it needs to be used in a custom validator function\n    if (!shouldFocus) {\n      return;\n    }\n\n    // eslint-disable-next-line ember/no-runloop\n    this.timer = schedule('afterRender', this, function () {\n      this.timer = undefined;\n      (\n        document.body.querySelector(\n          '#ember-a11y-refocus-nav-message',\n        ) as HTMLElement\n      )?.focus();\n    });\n  };\n\n  handleSkipLinkFocus = () => {\n    this.isSkipLinkFocused = !this.isSkipLinkFocused;\n  };\n\n  <template>\n    <div\n      tabindex=\"-1\"\n      id=\"ember-a11y-refocus-nav-message\"\n      class=\"ember-sr-only ember-sr-only-focusable\"\n    >\n      {{this.navigationText}}\n    </div>\n\n    {{#if this.skipLink}}\n      <a\n        href={{this.skipTo}}\n        id=\"ember-a11y-refocus-skip-link\"\n        class=\"ember-a11y-refocus-skip-link\n          {{if this.isSkipLinkFocused 'active'}}\"\n        {{on \"focus\" this.handleSkipLinkFocus}}\n        {{on \"blur\" this.handleSkipLinkFocus}}\n      >\n        {{this.skipText}}\n      </a>\n    {{/if}}\n  </template>\n}\n"],"names":["NavigationNarrator","Component","g","prototype","service","i","tracked","timer","transition","constructor","owner","args","router","on","onRouteChange","registerDestructor","cancel","undefined","off","skipLink","skipTo","skipText","navigationText","routeChangeValidator","defaultValidator","excludeAllQueryParams","hasQueryParams","Object","keys","from","queryParams","length","to","hasSameRoute","name","shouldFocus","schedule","document","body","querySelector","focus","handleSkipLinkFocus","isSkipLinkFocused","setComponentTemplate","precompileTemplate","strictMode","scope"],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { default as NavigationNarrator } from './components/navigation-narrator.js';
+export { defaultValidator } from './utils/validators.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/styles/navigation-narrator.css

@@ -0,0 +1,27 @@
+#ember-a11y-refocus-nav-message {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+.ember-a11y-refocus-skip-link {
+  position: absolute;
+  left: 0;
+  top: 0;
+  background-color: rgb(0 0 0 / 75%);
+  font-size: 0.75rem;
+  color: #fff;
+  padding: 0.25rem;
+  text-decoration: none;
+  transform: translateY(-100%);
+  transition: transform 0.3s ease-in-out;
+}
+
+.ember-a11y-refocus-skip-link:focus {
+  transform: translateY(0);
+}

package/dist/template-registry.js

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=template-registry.js.map

package/dist/template-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-registry.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/utils/routing.js

@@ -0,0 +1,37 @@
+/**
+ * Returns true if the given RouteInfo objects represent the same route in the
+ * tree, with matching params and query params.
+ */
+function routeInfoEqual(a, b) {
+  let current_a = a;
+  let current_b = b;
+  do {
+    if (!current_a || !current_b) {
+      return false;
+    }
+    if (current_a.name !== current_b.name) {
+      return false;
+    }
+    if (!shallowEqual(current_a.params, current_b.params)) {
+      return false;
+    }
+    if (!shallowEqual(current_a.queryParams, current_b.queryParams)) {
+      return false;
+    }
+    current_a = current_a.parent;
+    current_b = current_b.parent;
+  } while (current_a || current_b);
+  return true;
+}
+function shallowEqual(a, b) {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    if (a[key] !== b[key]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export { routeInfoEqual };
+//# sourceMappingURL=routing.js.map

package/dist/utils/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sources":["../../src/utils/routing.ts"],"sourcesContent":["import type RouteInfo from '@ember/routing/route-info';\n\nexport interface RouteInfoLike {\n  name: string;\n  params: Record<string, unknown>;\n  queryParams: Record<string, unknown>;\n  parent: RouteInfoLike | RouteInfo | null;\n}\n\n/**\n * Returns true if the given RouteInfo objects represent the same route in the\n * tree, with matching params and query params.\n */\nexport function routeInfoEqual(\n  a: RouteInfoLike | RouteInfo | null | undefined | void,\n  b: RouteInfoLike | RouteInfo | null | undefined | void,\n): boolean {\n  let current_a: RouteInfoLike | RouteInfo | null | undefined | void = a;\n  let current_b: RouteInfoLike | RouteInfo | null | undefined | void = b;\n\n  do {\n    if (!current_a || !current_b) {\n      return false;\n    }\n\n    if (current_a.name !== current_b.name) {\n      return false;\n    }\n\n    if (\n      !shallowEqual(\n        current_a.params as Record<string, unknown>,\n        current_b.params as Record<string, unknown>,\n      )\n    ) {\n      return false;\n    }\n\n    if (\n      !shallowEqual(\n        current_a.queryParams as Record<string, unknown>,\n        current_b.queryParams as Record<string, unknown>,\n      )\n    ) {\n      return false;\n    }\n\n    current_a = current_a.parent;\n    current_b = current_b.parent;\n  } while (current_a || current_b);\n\n  return true;\n}\n\nfunction shallowEqual(\n  a: Record<string, unknown>,\n  b: Record<string, unknown>,\n): boolean {\n  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);\n\n  for (const key of keys) {\n    if (a[key] !== b[key]) {\n      return false;\n    }\n  }\n\n  return true;\n}\n"],"names":["routeInfoEqual","a","b","current_a","current_b","name","shallowEqual","params","queryParams","parent","keys","Set","Object","key"],"mappings":"AASA;AACA;AACA;AACA;AACO,SAASA,cAAcA,CAC5BC,CAAsD,EACtDC,CAAsD,EAC7C;EACT,IAAIC,SAA8D,GAAGF,CAAC;EACtE,IAAIG,SAA8D,GAAGF,CAAC;EAEtE,GAAG;AACD,IAAA,IAAI,CAACC,SAAS,IAAI,CAACC,SAAS,EAAE;AAC5B,MAAA,OAAO,KAAK;AACd,IAAA;AAEA,IAAA,IAAID,SAAS,CAACE,IAAI,KAAKD,SAAS,CAACC,IAAI,EAAE;AACrC,MAAA,OAAO,KAAK;AACd,IAAA;IAEA,IACE,CAACC,YAAY,CACXH,SAAS,CAACI,MAAM,EAChBH,SAAS,CAACG,MACZ,CAAC,EACD;AACA,MAAA,OAAO,KAAK;AACd,IAAA;IAEA,IACE,CAACD,YAAY,CACXH,SAAS,CAACK,WAAW,EACrBJ,SAAS,CAACI,WACZ,CAAC,EACD;AACA,MAAA,OAAO,KAAK;AACd,IAAA;IAEAL,SAAS,GAAGA,SAAS,CAACM,MAAM;IAC5BL,SAAS,GAAGA,SAAS,CAACK,MAAM;EAC9B,CAAC,QAAQN,SAAS,IAAIC,SAAS;AAE/B,EAAA,OAAO,IAAI;AACb;AAEA,SAASE,YAAYA,CACnBL,CAA0B,EAC1BC,CAA0B,EACjB;EACT,MAAMQ,IAAI,GAAG,IAAIC,GAAG,CAAC,CAAC,GAAGC,MAAM,CAACF,IAAI,CAACT,CAAC,CAAC,EAAE,GAAGW,MAAM,CAACF,IAAI,CAACR,CAAC,CAAC,CAAC,CAAC;AAE5D,EAAA,KAAK,MAAMW,GAAG,IAAIH,IAAI,EAAE;IACtB,IAAIT,CAAC,CAACY,GAAG,CAAC,KAAKX,CAAC,CAACW,GAAG,CAAC,EAAE;AACrB,MAAA,OAAO,KAAK;AACd,IAAA;AACF,EAAA;AAEA,EAAA,OAAO,IAAI;AACb;;;;"}

package/dist/utils/validators.js

@@ -0,0 +1,8 @@
+import { routeInfoEqual } from './routing.js';
+
+function defaultValidator(transition) {
+  return !routeInfoEqual(transition.from, transition.to);
+}
+
+export { defaultValidator };
+//# sourceMappingURL=validators.js.map

package/dist/utils/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sources":["../../src/utils/validators.ts"],"sourcesContent":["import { routeInfoEqual } from './routing.ts';\n\nimport type RouteInfo from '@ember/routing/route-info';\nimport type { RouteInfoLike } from './routing.ts';\n\ninterface TransitionLike {\n  from?: RouteInfoLike | RouteInfo | null | undefined | void;\n  to?: RouteInfoLike | RouteInfo | null | undefined | void;\n}\n\nexport function defaultValidator(transition: TransitionLike): boolean {\n  return !routeInfoEqual(transition.from, transition.to);\n}\n"],"names":["defaultValidator","transition","routeInfoEqual","from","to"],"mappings":";;AAUO,SAASA,gBAAgBA,CAACC,UAA0B,EAAW;EACpE,OAAO,CAACC,cAAc,CAACD,UAAU,CAACE,IAAI,EAAEF,UAAU,CAACG,EAAE,CAAC;AACxD;;;;"}

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "@ohos-ports/ember-a11y-refocus",
+  "version": "5.2.1-beta.1",
+  "description": "Accessibility addon to announce route change, reset focus, and provide a skip link",
+  "keywords": [
+    "ember-addon",
+    "accessibility",
+    "a11y",
+    "skiplink"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ohos-ports/ohos-ports.git",
+    "directory": "ports/ember-a11y-refocus/5.2.1"
+  },
+  "license": "MIT",
+  "author": "Melanie Sumner <melaniersumner@gmail.com>",
+  "contributors": [
+    {
+      "name": "Alexey Kulakov"
+    }
+  ],
+  "imports": {
+    "#src/*": "./src/*"
+  },
+  "exports": {
+    ".": {
+      "types": "./declarations/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./addon-main.js": "./addon-main.cjs",
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./declarations/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "addon-main.cjs",
+    "declarations",
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@embroider/addon-shim": "^1.10.2",
+    "decorator-transforms": "^2.3.1"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.0",
+    "@babel/eslint-parser": "^7.28.6",
+    "@babel/plugin-transform-typescript": "^7.28.6",
+    "@babel/runtime": "^7.28.6",
+    "@ember/app-tsconfig": "^2.0.0",
+    "@ember/library-tsconfig": "^2.0.0",
+    "@ember/test-helpers": "^5.4.1",
+    "@ember/test-waiters": "^4.1.1",
+    "@embroider/addon-dev": "^8.3.0",
+    "@embroider/compat": "^4.1.13",
+    "@embroider/core": "^4.4.3",
+    "@embroider/macros": "^1.19.7",
+    "@embroider/vite": "^1.5.2",
+    "@eslint/js": "^9.39.3",
+    "@glint/ember-tsc": "^1.1.1",
+    "@glint/template": "^1.7.4",
+    "@glint/tsserver-plugin": "^2.1.0",
+    "@ohos-ports/glimmer-component": "^2.1.1-beta.0",
+    "@ohos-ports/rollup": "^4.62.2-beta.2",
+    "@rollup/plugin-babel": "^6.1.0",
+    "@types/qunit": "^2.19.13",
+    "babel-plugin-ember-template-compilation": "^4.0.0",
+    "concurrently": "^9.2.1",
+    "ember-page-title": "^9.0.3",
+    "ember-qunit": "^9.0.4",
+    "ember-source": "^6.11.0",
+    "ember-strict-application-resolver": "^0.1.1",
+    "ember-template-lint": "^7.9.3",
+    "eslint": "^9.39.3",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ember": "^12.7.5",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-n": "^17.24.0",
+    "globals": "^17.3.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-ember-template-tag": "^2.1.3",
+    "publint": "^0.3.17",
+    "qunit": "^2.25.0",
+    "qunit-dom": "^3.5.0",
+    "release-plan": "^0.17.4",
+    "rollup-plugin-copy": "^3.5.0",
+    "testem": "^3.17.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.56.0",
+    "vite": "^7.3.1"
+  },
+  "engines": {
+    "node": "22.x",
+    "pnpm": ">= 10"
+  },
+  "ember": {
+    "edition": "octane"
+  },
+  "ember-addon": {
+    "version": 2,
+    "type": "addon",
+    "main": "addon-main.cjs",
+    "app-js": {
+      "./components/navigation-narrator.js": "./dist/_app_/components/navigation-narrator.js"
+    }
+  },
+  "scripts": {
+    "build": "rollup --config",
+    "format": "prettier . --cache --write",
+    "lint": "concurrently \"pnpm:lint:*(!fix)\" --names \"lint:\" --prefixColors auto",
+    "lint:fix": "concurrently \"pnpm:lint:*:fix\" --names \"fix:\" --prefixColors auto && pnpm run format",
+    "lint:format": "prettier . --cache --check",
+    "lint:hbs": "ember-template-lint . --no-error-on-unmatched-pattern",
+    "lint:hbs:fix": "ember-template-lint . --fix --no-error-on-unmatched-pattern",
+    "lint:js": "eslint . --cache",
+    "lint:js:fix": "eslint . --fix",
+    "lint:publish": "pnpm build && publint run --level error",
+    "lint:types": "ember-tsc --noEmit",
+    "start": "vite dev",
+    "test": "vite build --mode=development --out-dir dist-tests && testem --file testem.cjs ci --port 0"
+  },
+  "bugs": {
+    "url": "https://github.com/ohos-ports/ohos-ports/issues"
+  }
+}

package/src/components/navigation-narrator.gts

@@ -0,0 +1,175 @@
+import Component from '@glimmer/component';
+import { service } from '@ember/service';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { registerDestructor } from '@ember/destroyable';
+import { schedule, cancel } from '@ember/runloop';
+
+import { defaultValidator } from '../utils/validators.ts';
+
+import type RouterService from '@ember/routing/router-service';
+import type Owner from '@ember/owner';
+import type Transition from '@ember/routing/transition';
+import type { Timer } from '@ember/runloop';
+
+export interface NavigationNarratorSignature {
+  Args: {
+    /** Whether to include the skip link. Defaults to `true`. */
+    skipLink?: boolean;
+
+    /** CSS selector the skip link jumps to. Defaults to `'#main'`. */
+    skipTo?: string;
+
+    /** Text content of the skip link. Defaults to `'Skip to main content'`. */
+    skipText?: string;
+
+    /** Text announced by a screen reader after navigation. */
+    navigationText?: string;
+
+    /** Custom logic for determining whether a transition should trigger narration. */
+    routeChangeValidator?: (transition: Transition) => boolean;
+
+    /** Whether to ignore query param changes during route comparisons. Defaults to `false`. */
+    excludeAllQueryParams?: boolean;
+  };
+
+  Element: HTMLElement;
+}
+
+/**
+ * 🎧 NavigationNarrator
+ *
+ * Announces route changes for screen readers using a visually-hidden element,
+ * and optionally renders a "Skip to main content" link.
+ *
+ * Usage:
+ * ```gjs
+ * import { NavigationNarrator } from 'ember-a11y-refocus';
+ *
+ * <template>
+ *   <NavigationNarrator />
+ * </template>
+ * ```
+ */
+export default class NavigationNarrator extends Component<NavigationNarratorSignature> {
+  @service declare readonly router: RouterService;
+
+  @tracked isSkipLinkFocused = false;
+
+  timer: Timer | undefined;
+  transition: Transition | undefined;
+
+  constructor(owner: Owner, args: NavigationNarratorSignature['Args']) {
+    super(owner, args);
+
+    this.router.on('routeDidChange', this.onRouteChange);
+
+    registerDestructor(this, () => {
+      // eslint-disable-next-line ember/no-runloop
+      cancel(this.timer);
+      this.timer = undefined;
+      this.router.off('routeDidChange', this.onRouteChange);
+    });
+  }
+
+  /** Whether to include the skip link. Defaults to `true`. */
+  get skipLink() {
+    return this.args.skipLink ?? true;
+  }
+
+  /** Selector for the skip link target. Defaults to `'#main'`. */
+  get skipTo() {
+    return this.args.skipTo ?? '#main';
+  }
+
+  /** Text for the skip link. Defaults to `'Skip to main content'`. */
+  get skipText() {
+    return this.args.skipText ?? 'Skip to main content';
+  }
+
+  /** Text announced by screen readers after route transition. */
+  get navigationText() {
+    return (
+      this.args.navigationText ??
+      'The page navigation is complete. You may now navigate the page content as you wish.'
+    );
+  }
+
+  /** Validator function for transitions. */
+  get routeChangeValidator() {
+    return this.args.routeChangeValidator ?? defaultValidator;
+  }
+
+  /** Whether to ignore query param changes. Defaults to `false`. */
+  get excludeAllQueryParams() {
+    return this.args.excludeAllQueryParams ?? false;
+  }
+
+  /** Whether the current transition includes query param changes. */
+  get hasQueryParams() {
+    if (
+      Object.keys(this.transition?.from?.queryParams || {}).length ||
+      Object.keys(this.transition?.to?.queryParams || {}).length > 0
+    ) {
+      return true;
+    } else {
+      return false;
+    }
+  }
+
+  onRouteChange = (transition: Transition) => {
+    this.transition = transition; // We need to do this because we can't pass an argument to a getter
+
+    // add a check to see if it's the same route
+    const hasSameRoute =
+      this.transition.from?.name === this.transition.to?.name;
+
+    if (this.excludeAllQueryParams && this.hasQueryParams && hasSameRoute) {
+      return;
+    }
+
+    const shouldFocus = this.routeChangeValidator(transition);
+
+    // leaving this here for now because maybe it needs to be used in a custom validator function
+    if (!shouldFocus) {
+      return;
+    }
+
+    // eslint-disable-next-line ember/no-runloop
+    this.timer = schedule('afterRender', this, function () {
+      this.timer = undefined;
+      (
+        document.body.querySelector(
+          '#ember-a11y-refocus-nav-message',
+        ) as HTMLElement
+      )?.focus();
+    });
+  };
+
+  handleSkipLinkFocus = () => {
+    this.isSkipLinkFocused = !this.isSkipLinkFocused;
+  };
+
+  <template>
+    <div
+      tabindex="-1"
+      id="ember-a11y-refocus-nav-message"
+      class="ember-sr-only ember-sr-only-focusable"
+    >
+      {{this.navigationText}}
+    </div>
+
+    {{#if this.skipLink}}
+      <a
+        href={{this.skipTo}}
+        id="ember-a11y-refocus-skip-link"
+        class="ember-a11y-refocus-skip-link
+          {{if this.isSkipLinkFocused 'active'}}"
+        {{on "focus" this.handleSkipLinkFocus}}
+        {{on "blur" this.handleSkipLinkFocus}}
+      >
+        {{this.skipText}}
+      </a>
+    {{/if}}
+  </template>
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { default as NavigationNarrator } from './components/navigation-narrator.gts';
+export { defaultValidator } from './utils/validators.ts';

package/src/styles/navigation-narrator.css

@@ -0,0 +1,27 @@
+#ember-a11y-refocus-nav-message {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+.ember-a11y-refocus-skip-link {
+  position: absolute;
+  left: 0;
+  top: 0;
+  background-color: rgb(0 0 0 / 75%);
+  font-size: 0.75rem;
+  color: #fff;
+  padding: 0.25rem;
+  text-decoration: none;
+  transform: translateY(-100%);
+  transition: transform 0.3s ease-in-out;
+}
+
+.ember-a11y-refocus-skip-link:focus {
+  transform: translateY(0);
+}

package/src/template-registry.ts

@@ -0,0 +1,9 @@
+// Easily allow apps, which are not yet using strict mode templates, to consume your Glint types, by importing this file.
+// Add all your components, helpers and modifiers to the template registry here, so apps don't have to do this.
+// See https://typed-ember.gitbook.io/glint/environments/ember/authoring-addons
+
+import type NavigationNarrator from './components/navigation-narrator.gts';
+
+export default interface EmberA11yRefocusRegistry {
+  NavigationNarrator: typeof NavigationNarrator;
+}

package/src/utils/routing.ts

@@ -0,0 +1,68 @@
+import type RouteInfo from '@ember/routing/route-info';
+
+export interface RouteInfoLike {
+  name: string;
+  params: Record<string, unknown>;
+  queryParams: Record<string, unknown>;
+  parent: RouteInfoLike | RouteInfo | null;
+}
+
+/**
+ * Returns true if the given RouteInfo objects represent the same route in the
+ * tree, with matching params and query params.
+ */
+export function routeInfoEqual(
+  a: RouteInfoLike | RouteInfo | null | undefined | void,
+  b: RouteInfoLike | RouteInfo | null | undefined | void,
+): boolean {
+  let current_a: RouteInfoLike | RouteInfo | null | undefined | void = a;
+  let current_b: RouteInfoLike | RouteInfo | null | undefined | void = b;
+
+  do {
+    if (!current_a || !current_b) {
+      return false;
+    }
+
+    if (current_a.name !== current_b.name) {
+      return false;
+    }
+
+    if (
+      !shallowEqual(
+        current_a.params as Record<string, unknown>,
+        current_b.params as Record<string, unknown>,
+      )
+    ) {
+      return false;
+    }
+
+    if (
+      !shallowEqual(
+        current_a.queryParams as Record<string, unknown>,
+        current_b.queryParams as Record<string, unknown>,
+      )
+    ) {
+      return false;
+    }
+
+    current_a = current_a.parent;
+    current_b = current_b.parent;
+  } while (current_a || current_b);
+
+  return true;
+}
+
+function shallowEqual(
+  a: Record<string, unknown>,
+  b: Record<string, unknown>,
+): boolean {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+
+  for (const key of keys) {
+    if (a[key] !== b[key]) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/utils/validators.ts

@@ -0,0 +1,13 @@
+import { routeInfoEqual } from './routing.ts';
+
+import type RouteInfo from '@ember/routing/route-info';
+import type { RouteInfoLike } from './routing.ts';
+
+interface TransitionLike {
+  from?: RouteInfoLike | RouteInfo | null | undefined | void;
+  to?: RouteInfoLike | RouteInfo | null | undefined | void;
+}
+
+export function defaultValidator(transition: TransitionLike): boolean {
+  return !routeInfoEqual(transition.from, transition.to);
+}