@inglorious/web 6.9.0 → 6.10.0

package/README.md

@@ -89,7 +89,7 @@ It's that simple — and surprisingly fast in practice.
 - You want UI to be fully controlled by your entity-based store
 - You want to stay entirely in **JavaScript**, without DSLs or compilers
 - You want **React-like declarative UI** but without the cost and overhead of React
-- You want to build **static sites with SSX** — same entity patterns, pre-rendered HTML, and client hydration
+- You want **pre-rendered sites with SSX**, static or server-rendered on request — same entity patterns, HTML from the server, and client hydration
 
 This framework is ideal for both small apps and large business UIs.
 
@@ -289,7 +289,7 @@ import { createStore } from "@inglorious/store"
 import { html } from "@inglorious/web"
 
 const types = {
-  counter: {
+  Counter: {
     increment(entity) {
       entity.value++
     },
@@ -1282,6 +1282,7 @@ api.notify("geolocationUnwatch")
 
 ```javascript
 import { mount, html } from "@inglorious/web"
+import { when } from "@inglorious/web/directives/when"
 import { store } from "./store.js"
 
 const renderApp = (api) => {
@@ -1295,12 +1296,13 @@ const renderApp = (api) => {
       <p>Loading: ${geolocation.isLoading ? "yes" : "no"}</p>
       <p>
         Position:
-        ${
-          position
-            ? html`${position.coords.latitude.toFixed(4)},
-              ${position.coords.longitude.toFixed(4)}`
-            : "unknown"
-        }
+        ${when(
+          position,
+          () =>
+            html`${position.coords.latitude.toFixed(4)},
+            ${position.coords.longitude.toFixed(4)}`,
+          () => "unknown",
+        )}
       </p>
       <p>Error: ${geolocation.error ? geolocation.error.message : "none"}</p>
       <button
@@ -1461,11 +1463,13 @@ Events:
 
 ```javascript
 const renderUpdate = (api) =>
-  api.getEntity("pwaUpdate").isUpdateReady
-    ? html`<button @click=${() => api.notify("#pwaUpdate:pwaUpdateApply")}>
+  when(
+    api.getEntity("pwaUpdate").isUpdateReady,
+    () =>
+      html`<button @click=${() => api.notify("#pwaUpdate:pwaUpdateApply")}>
         Update now
-      </button>`
-    : ""
+      </button>`,
+  )
 ```
 
 Inglorious UI's `Snackbar` is the usual place for it. `watchPwaUpdate` takes `{ id, checkEveryMs }` as a third argument, to announce to an entity with another id or to check more or less often, and returns a function that stops watching.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "6.9.0",
+  "version": "6.10.0",
   "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,83 @@
+const ANNOUNCER_ID = "iw-route-announcer"
+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
+
+  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
+    announcer.textContent =
+      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
 }
 
 /**