@inglorious/web 6.8.1 → 6.9.1

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++
     },
@@ -971,6 +971,7 @@ To enable the router, add it to your store's types and create a `router` entity.
 // store.js
 import { createStore } from "@inglorious/store"
 import { html } from "@inglorious/web"
+import { PwaUpdate, watchPwaUpdate } from "@inglorious/web/pwa"
 import { Router, setRoutes } from "@inglorious/web/router"
 
 const types = {
@@ -1281,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) => {
@@ -1294,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
@@ -1410,6 +1413,69 @@ mount(store, renderApp, document.getElementById("root"))
 
 ---
 
+## PWA Updates
+
+`@inglorious/web/pwa` keeps an installed PWA on its latest version. It works with the service worker that [`vite-plugin-pwa`](https://vite-pwa-org.netlify.app/) generates, and `@inglorious/create-app --pwa` sets it up for you.
+
+Updates are not optional. A new version downloads in the background, and is applied with a reload at the first moment nobody is in the middle of something:
+
+- at launch, before anything is touched;
+- each time the app goes to the background or comes back to the foreground.
+
+It also checks for a new version every hour and on every return to the foreground: a phone suspends an installed PWA rather than closing it, so the browser's own check may never come.
+
+```javascript
+import { isNative } from "@inglorious/web/mobile"
+import { watchPwaUpdate } from "@inglorious/web/pwa"
+import { registerSW } from "virtual:pwa-register"
+
+if (!isNative()) {
+  registerSW({
+    onRegisteredSW(url, registration) {
+      if (registration) watchPwaUpdate(registration)
+    },
+  })
+}
+```
+
+Configure the plugin with `registerType: "prompt"` and `injectRegister: false`: the generated worker then waits for the `SKIP_WAITING` message this module sends, instead of taking over on its own.
+
+### Offering "Update now"
+
+A version that lands while someone is using the app waits for the next trip to the background. To offer it right away, pass the store and register the `PwaUpdate` type:
+
+```javascript
+import { PwaUpdate, watchPwaUpdate } from "@inglorious/web/pwa"
+
+const store = createStore({ types: { PwaUpdate }, autoCreateEntities: true })
+
+watchPwaUpdate(registration, store)
+```
+
+The `pwaUpdate` entity contains:
+
+- `isUpdateReady` — a new version is waiting for the next reload
+
+Events:
+
+- `pwaUpdateReady` — sent by `watchPwaUpdate` when a version lands mid-session
+- `pwaUpdateApply` — moves over to the waiting version now, reloading the page
+
+```javascript
+const renderUpdate = (api) =>
+  when(
+    api.getEntity("pwaUpdate").isUpdateReady,
+    () =>
+      html`<button @click=${() => api.notify("#pwaUpdate:pwaUpdateApply")}>
+        Update now
+      </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.
+
+---
+
 ## Forms
 
 `@inglorious/web` includes a small but powerful `form` type for managing form state inside your entity store. It offers:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "6.8.1",
+  "version": "6.9.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": [
@@ -58,6 +58,10 @@
       "types": "./types/mobile.d.ts",
       "import": "./src/mobile/index.js"
     },
+    "./pwa": {
+      "types": "./types/pwa.d.ts",
+      "import": "./src/pwa/index.js"
+    },
     "./router": {
       "types": "./types/router.d.ts",
       "import": "./src/router/index.js"
@@ -113,7 +117,7 @@
     "@inglorious/store": "12.0.0"
   },
   "devDependencies": {
-    "@inglorious/eslint-config": "1.1.4",
+    "@inglorious/eslint-config": "1.2.0",
     "prettier": "^3.9.6",
     "typescript": "~7.0.2",
     "vitest": "^5.0.0"

package/src/pwa/handlers.js

@@ -0,0 +1,17 @@
+/**
+ * @typedef {import("../../types/pwa.js").PwaUpdateEntity} PwaUpdateEntity
+ */
+
+import { applyPwaUpdate } from "./update.js"
+
+export function create(entity) {
+  entity.isUpdateReady ??= false
+}
+
+export function pwaUpdateApply() {
+  applyPwaUpdate()
+}
+
+export function pwaUpdateReady(entity) {
+  entity.isUpdateReady = true
+}

package/src/pwa/index.js

@@ -0,0 +1,5 @@
+import * as handlers from "./handlers.js"
+
+export { applyPwaUpdate, watchPwaUpdate } from "./update.js"
+
+export const PwaUpdate = { ...handlers }

package/src/pwa/update.js

@@ -0,0 +1,114 @@
+const ONE_HOUR_MS = 3_600_000
+const TAKEOVER_TIMEOUT_MS = 3_000
+const DEFAULT_ID = "pwaUpdate"
+const VISIBILITY_EVENT = "visibilitychange"
+
+/**
+ * Keeps an installed PWA on its latest version. Updates are not optional: a
+ * downloaded version is applied on its own wherever nobody is mid-task — at
+ * boot, before anything is touched, and each time the app leaves or comes
+ * back to the foreground. A version that lands while someone is using the
+ * app is only announced, as `#${id}:pwaUpdateReady`, so the app can offer to
+ * move over at once; the next trip to the background moves over regardless.
+ *
+ * Checks for a new version every `checkEveryMs` and on each return to the
+ * foreground: a phone suspends an installed PWA rather than closing it, so
+ * the browser's own check on navigation may never come.
+ *
+ * @param {ServiceWorkerRegistration} registration What `registerSW` from
+ *   `virtual:pwa-register` hands to `onRegisteredSW`.
+ * @param {{ notify: (type: string, payload?: unknown) => void }} [store]
+ *   Where to announce a mid-session version. Without one, updates are applied
+ *   silently.
+ * @param {{ id?: string, checkEveryMs?: number }} [options]
+ * @returns {() => void} Stops watching.
+ */
+export function watchPwaUpdate(
+  registration,
+  store,
+  { id = DEFAULT_ID, checkEveryMs = ONE_HOUR_MS } = {},
+) {
+  // A first-ever install has no older version to move from: nothing to
+  // announce while the page that installed it keeps running.
+  const hadController = Boolean(navigator.serviceWorker?.controller)
+  let announced = null
+  let isApplying = false
+
+  apply()
+  watchInstalls()
+  const interval = setInterval(check, checkEveryMs)
+  document.addEventListener(VISIBILITY_EVENT, handleVisibilityChange)
+
+  return function stop() {
+    clearInterval(interval)
+    document.removeEventListener(VISIBILITY_EVENT, handleVisibilityChange)
+  }
+
+  // Offline, the check fails: the next one tries again.
+  function check() {
+    registration.update?.()?.catch?.(() => {})
+  }
+
+  function handleVisibilityChange() {
+    if (apply()) return
+    if (!document.hidden) check()
+  }
+
+  // One reload per waiting worker: the hidden and visible events of a single
+  // trip to the background must not send it twice, nor check for another
+  // version while the reload is on its way.
+  function apply() {
+    if (isApplying) return true
+    if (!registration.waiting) return false
+    isApplying = true
+    applyPwaUpdate(registration)
+    return true
+  }
+
+  function announce(worker) {
+    if (!hadController || isApplying || announced === worker) return
+    announced = worker
+    store?.notify(`#${id}:pwaUpdateReady`)
+  }
+
+  function watchInstalls() {
+    if (registration.waiting) announce(registration.waiting)
+    registration.addEventListener("updatefound", () => {
+      const worker = registration.installing
+      worker?.addEventListener("statechange", () => {
+        if (worker.state === "installed") announce(worker)
+        if (worker.state === "activated") announced = null
+      })
+    })
+  }
+}
+
+/**
+ * Moves the page over to the waiting version: asks the worker to take over
+ * with the SKIP_WAITING message that workbox's generated worker listens for,
+ * and reloads once it has — not before, or the page just reopens on the old
+ * version. With nothing waiting it simply reloads.
+ *
+ * @param {ServiceWorkerRegistration} [registration] Looked up when omitted.
+ * @returns {Promise<void>}
+ */
+export async function applyPwaUpdate(registration) {
+  const target =
+    registration ?? (await navigator.serviceWorker?.getRegistration())
+  const worker = target?.waiting
+  if (worker) await takeOver(worker)
+  location.reload()
+}
+
+// Bounded: a worker that never reports back still gets the page reloaded.
+function takeOver(worker) {
+  return new Promise((resolve) => {
+    const timeout = setTimeout(resolve, TAKEOVER_TIMEOUT_MS)
+    worker.addEventListener("statechange", () => {
+      if (worker.state !== "activated") return
+      clearTimeout(timeout)
+      resolve()
+    })
+    worker.postMessage({ type: "SKIP_WAITING" })
+  })
+}

package/types/pwa.d.ts

@@ -0,0 +1,41 @@
+import { Api } from "./mount"
+
+export interface PwaUpdateEntity {
+  id?: string
+  type: string
+  /** A new version landed mid-session and waits for the next reload. */
+  isUpdateReady: boolean
+}
+
+export type PwaUpdateType = {
+  create(entity: PwaUpdateEntity): void
+  /** Moves over to the waiting version now, reloading the page. */
+  pwaUpdateApply(): void
+  pwaUpdateReady(entity: PwaUpdateEntity): void
+}
+
+export declare const PwaUpdate: PwaUpdateType
+
+export interface WatchPwaUpdateOptions {
+  /** The PwaUpdate entity to announce to. Defaults to `pwaUpdate`. */
+  id?: string
+  /** How often to check for a new version. Defaults to one hour. */
+  checkEveryMs?: number
+}
+
+/**
+ * Keeps an installed PWA on its latest version, applying a downloaded one at
+ * boot and on each trip to or from the background. A version that lands
+ * mid-session is announced to `store` as `#${id}:pwaUpdateReady`.
+ * @returns A function that stops watching.
+ */
+export declare function watchPwaUpdate(
+  registration: ServiceWorkerRegistration,
+  store?: Pick<Api, "notify">,
+  options?: WatchPwaUpdateOptions,
+): () => void
+
+/** Moves the page over to the waiting version and reloads. */
+export declare function applyPwaUpdate(
+  registration?: ServiceWorkerRegistration,
+): Promise<void>