@inglorious/web 6.9.1 → 6.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "6.9.1",
+  "version": "6.10.1",
   "description": "A new web framework that leverages the power of the Inglorious Store combined with the performance and simplicity of lit-html.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "contributors": [
@@ -114,7 +114,7 @@
     "lit-html": "^3.3.3"
   },
   "peerDependencies": {
-    "@inglorious/store": "12.0.0"
+    "@inglorious/store": "12.1.0"
   },
   "devDependencies": {
     "@inglorious/eslint-config": "1.2.0",

package/src/mount.js

@@ -6,17 +6,25 @@
 import { html, render } from "lit-html"
 
 import { isNative } from "./mobile/index.js"
+import { createAccessibleNavigation } from "./router/accessible-navigation.js"
 
 /**
  * Mounts a lit-html template to the DOM and subscribes to a store for re-rendering.
  * @param {Store} store - The application state store.
  * @param {(api: Api) => TemplateResult | null} renderFn - The root render function.
  * @param {HTMLElement | DocumentFragment} element - The DOM element to mount the template to.
- * @param {Object} [options] - Root error-boundary options.
+ * In an app with the `Router` type, each navigation is also announced to screen readers
+ * and moves focus back to the top of the new page, as a full page load would.
+ *
+ * @param {Object} [options] - Root error-boundary and navigation options.
  * @param {(error: unknown, api: Api) => void} [options.onError] - Called when the
  *   root render throws. Defaults to `console.error`.
  * @param {(error: unknown, api: Api) => TemplateResult | null} [options.fallback] -
  *   Optional fallback template rendered in place of the failed root render.
+ * @param {boolean} [options.hasAccessibleNavigation=true] - Whether navigations are
+ *   announced and move focus. Only apps with the `Router` type navigate.
+ * @param {() => string | null} [options.getPageName] - The name to announce for the
+ *   current page, or `null` while it is not known yet; by default the document title.
  * @returns {() => void} An unsubscribe function
  */
 export async function mount(store, renderFn, element, options = {}) {
@@ -24,6 +32,8 @@ export async function mount(store, renderFn, element, options = {}) {
     onError = defaultOnError,
     fallback,
     hydrate: allowHydrate = true,
+    hasAccessibleNavigation = true,
+    getPageName,
   } = options
 
   // Tells CSS the native app from a browser tab, which env() cannot: the
@@ -48,6 +58,11 @@ export async function mount(store, renderFn, element, options = {}) {
     }
   }
 
+  const afterRender =
+    hasAccessibleNavigation && store.getType("Router")
+      ? createAccessibleNavigation({ getPageName })
+      : null
+
   const unsubscribe = store.subscribe(() => {
     const result = renderRoot(renderFn, api, onError, fallback)
     if (result.ok) {
@@ -56,6 +71,7 @@ export async function mount(store, renderFn, element, options = {}) {
     } else if (fallback) {
       render(result.fallback, element)
     }
+    afterRender?.()
   })
 
   store.notify("init")

package/src/router/accessible-navigation.js

@@ -0,0 +1,95 @@
+const ANNOUNCER_ID = "iw-route-announcer"
+// Long enough for screen readers to notice the live region emptied first.
+const ANNOUNCE_DELAY_MS = 100
+const VISUALLY_HIDDEN =
+  "position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0"
+
+/**
+ * Makes client-side navigation do for assistive technology what a full page load does:
+ * the new page is announced to screen readers, and focus moves back to the top of the
+ * document, so the next Tab starts from the beginning of the new page. An element with
+ * `autofocus` on the new page gets the focus instead.
+ *
+ * A navigation leaves focus where it is when its history state has `isFocusKept`,
+ * which a link sets with `data-is-focus-kept`. The page is still announced.
+ *
+ * `mount` calls the function this returns after each render, so the new page is in
+ * the document by the time focus moves.
+ *
+ * @param {Object} [options]
+ * @param {() => string | null} [options.getPageName] - The name of the current page, or
+ *   `null` to be asked again after the next render; by default the document title.
+ * @returns {() => void} The function to call after each render.
+ */
+export function createAccessibleNavigation({
+  getPageName = () => document.title,
+} = {}) {
+  // Screen readers only announce changes made after the live region is in the document.
+  const announcer = getAnnouncer()
+  let currentPath = window.location.pathname
+  let hasPendingAnnouncement = false
+  let announceTimeout = null
+
+  // Screen readers speak only when the live region changes, so it is emptied first and
+  // filled on a later task: two pages with the same name are each announced.
+  function announce(message) {
+    announcer.textContent = ""
+    clearTimeout(announceTimeout)
+    announceTimeout = setTimeout(() => {
+      announcer.textContent = message
+    }, ANNOUNCE_DELAY_MS)
+  }
+
+  return function afterRender() {
+    const path = window.location.pathname
+    if (path !== currentPath) {
+      currentPath = path
+      hasPendingAnnouncement = true
+
+      if (!window.history.state?.isFocusKept) {
+        resetFocus()
+      }
+    }
+
+    if (!hasPendingAnnouncement) return
+
+    const name = getPageName()
+    if (name == null) return
+
+    hasPendingAnnouncement = false
+    announce(name || document.querySelector("h1")?.textContent || path)
+  }
+}
+
+function getAnnouncer() {
+  const existing = document.getElementById(ANNOUNCER_ID)
+  if (existing) return existing
+
+  const announcer = document.createElement("div")
+  announcer.id = ANNOUNCER_ID
+  announcer.setAttribute("aria-live", "assertive")
+  announcer.setAttribute("aria-atomic", "true")
+  announcer.style.cssText = VISUALLY_HIDDEN
+  document.body.append(announcer)
+  return announcer
+}
+
+// Focusing the body makes the next Tab start from the top of the new page, rather
+// than from the link that was clicked, which may no longer exist.
+function resetFocus() {
+  const autofocus = document.querySelector("[autofocus]")
+  if (autofocus) {
+    autofocus.focus()
+    return
+  }
+
+  const { body } = document
+  const tabIndex = body.getAttribute("tabindex")
+  body.tabIndex = -1
+  body.focus({ preventScroll: true })
+  if (tabIndex === null) {
+    body.removeAttribute("tabindex")
+  } else {
+    body.setAttribute("tabindex", tabIndex)
+  }
+}

package/src/router/handlers.js

@@ -86,6 +86,16 @@ export function createHandlers(routeConfig) {
         event.preventDefault()
 
         const path = link.pathname + link.search + link.hash
+
+        // Stored in the history entry, for whatever moves focus after navigating.
+        if (link.hasAttribute("data-is-focus-kept")) {
+          api.notify(`#${entityId}:navigate`, {
+            to: path,
+            state: { isFocusKept: true },
+          })
+          return
+        }
+
         api.notify(`#${entityId}:navigate`, path)
       })
     },

package/types/mount.d.ts

@@ -57,6 +57,16 @@ export interface MountOptions<
     error: unknown,
     api: Api<TEntity, TState>,
   ) => TemplateResult | null
+  /**
+   * Whether navigations are announced to screen readers and move focus to the top of the
+   * new page. Only apps with the `Router` type navigate. Defaults to `true`.
+   */
+  hasAccessibleNavigation?: boolean
+  /**
+   * The name to announce for the current page, or `null` while it is not known yet.
+   * Defaults to the document title.
+   */
+  getPageName?: () => string | null
 }
 
 /**