@inglorious/web 6.11.0 → 6.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "6.11.0",
+  "version": "6.12.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": [
@@ -66,6 +66,10 @@
       "types": "./types/pwa.d.ts",
       "import": "./src/pwa/index.js"
     },
+    "./push": {
+      "types": "./types/push.d.ts",
+      "import": "./src/push/index.js"
+    },
     "./router": {
       "types": "./types/router.d.ts",
       "import": "./src/router/index.js"
@@ -127,7 +131,7 @@
     "vitest": "^5.0.0"
   },
   "engines": {
-    "node": ">= 22"
+    "node": ">= 26"
   },
   "scripts": {
     "format": "prettier --write .",

package/src/push/index.js

@@ -0,0 +1,142 @@
+import { handleAsync } from "@inglorious/store/async"
+
+const DEFAULT_DECLINE_KEY = "inglorious-push-declined"
+
+// The adapters whose taps are already wired: an entity created again (a hot
+// update, a second store) must not open each push twice.
+const tappedAdapters = new WeakSet()
+
+/**
+ * The type that asks a device for push notifications and keeps it registered.
+ *
+ * A device shows its permission dialog only so many times, and a refusal
+ * there may be for good. So the type asks in the app's own words first: an
+ * entity with `isOpen` the app renders as a prompt, whose yes brings up the
+ * system's dialog (`pushAsk`) and whose no (`pushDecline`) is remembered on
+ * the device, so it never asks again. Allowed later from the system's
+ * settings, pushes still register.
+ *
+ * The app tells it when there is someone to register for: `pushStart` (at
+ * sign-in) checks the permission, registers the device if it is granted, and
+ * otherwise opens the prompt; `pushStop` (at sign-out) closes it. Map them
+ * onto the app's own events, such as `sessionStart: type.pushStart`.
+ *
+ * Everything vendor-specific is the `adapter`'s:
+ *
+ * - `isSupported()`: whether this device can receive pushes at all.
+ * - `permission()`: `"granted"`, `"denied"` or `"prompt"`.
+ * - `request()`: brings up the system's dialog, resolving to the same. In a
+ *   browser it must call `Notification.requestPermission()` before it awaits
+ *   anything, since the dialog needs the tap that asked.
+ * - `register()`: gets the device's token and stores it for the signed-in
+ *   user. Unregistering is the app's to do at sign-out, while the user can
+ *   still delete their own token.
+ * - `onTap(listener)`, optional: calls `listener(url)` when a push is tapped,
+ *   where the system shows them itself (native apps). The type navigates
+ *   there with `onTap(url, api)`, by default `#router:navigate`.
+ *
+ * @param {Object} config
+ * @param {Object} config.adapter
+ * @param {string} [config.declineKey] - The localStorage key of a decline.
+ * @param {(url: string, api: Object) => void} [config.onTap]
+ *
+ * @example
+ * const prompt = createPushPrompt({ adapter: fcm })
+ * const types = {
+ *   PushPrompt: {
+ *     ...prompt,
+ *     ...renderers,
+ *     sessionStart: prompt.pushStart,
+ *     sessionEnd: prompt.pushStop,
+ *   },
+ * }
+ */
+export function createPushPrompt({
+  adapter,
+  declineKey = DEFAULT_DECLINE_KEY,
+  onTap = navigate,
+}) {
+  function isDeclined() {
+    try {
+      return window.localStorage.getItem(declineKey) !== null
+    } catch {
+      return false
+    }
+  }
+
+  return {
+    create(entity, _, api) {
+      entity.isOpen ??= false
+      entity.isActive ??= false
+      if (adapter.onTap && !tappedAdapters.has(adapter)) {
+        tappedAdapters.add(adapter)
+        adapter.onTap((url) => onTap(url, api))
+      }
+    },
+
+    pushStart(entity, _, api) {
+      entity.isActive = true
+      api.notify(`#${entity.id}:pushCheck`)
+    },
+
+    pushStop(entity) {
+      entity.isActive = false
+      entity.isOpen = false
+    },
+
+    // Asking the device is async, so a stop can land before the answer: the
+    // prompt only opens while started.
+    ...handleAsync("pushCheck", {
+      async run() {
+        if (!(await adapter.isSupported())) return null
+        return adapter.permission()
+      },
+      success(entity, permission, api) {
+        if (!entity.isActive) return
+        if (permission === "granted") {
+          api.notify(`#${entity.id}:pushRegister`)
+          return
+        }
+        entity.isOpen = permission === "prompt" && !isDeclined()
+      },
+      error() {},
+    }),
+
+    // The prompt goes down as the system's dialog comes up. Dismissing the
+    // dialog leaves the permission undecided, so the next start asks again.
+    ...handleAsync("pushAsk", {
+      start(entity) {
+        entity.isOpen = false
+      },
+      run() {
+        return adapter.request()
+      },
+      success(entity, permission, api) {
+        if (permission === "granted") api.notify(`#${entity.id}:pushRegister`)
+      },
+      error() {},
+    }),
+
+    pushDecline(entity) {
+      try {
+        window.localStorage.setItem(declineKey, "true")
+      } catch {
+        // Without storage the prompt comes back next start, nothing worse.
+      }
+      entity.isOpen = false
+    },
+
+    // Nothing on screen depends on it: a device that fails to register now
+    // tries again at the next start.
+    ...handleAsync("pushRegister", {
+      run() {
+        return adapter.register()
+      },
+      error() {},
+    }),
+  }
+}
+
+function navigate(url, api) {
+  api.notify("#router:navigate", url)
+}

package/types/push.d.ts

@@ -0,0 +1,54 @@
+import { Api } from "./mount"
+
+export type PushPermission = "granted" | "denied" | "prompt"
+
+/** Everything vendor-specific about pushes: the device, and where its token goes. */
+export interface PushAdapter {
+  /** Whether this device can receive pushes at all. */
+  isSupported(): Promise<boolean>
+  permission(): Promise<PushPermission>
+  /**
+   * Brings up the system's dialog. In a browser it must call
+   * `Notification.requestPermission()` before it awaits anything.
+   */
+  request(): Promise<PushPermission>
+  /** Gets the device's token and stores it for the signed-in user. */
+  register(): Promise<void>
+  /** Calls `listener(url)` when a push the system showed is tapped. */
+  onTap?(listener: (url: string) => void): void
+}
+
+export interface PushPromptConfig {
+  adapter: PushAdapter
+  /** The localStorage key of a decline. Defaults to `"inglorious-push-declined"`. */
+  declineKey?: string
+  /** Opens a tapped push's `url`. Defaults to `#router:navigate`. */
+  onTap?: (url: string, api: Api) => void
+}
+
+export interface PushPromptEntity {
+  id?: string
+  type: string
+  /** The app's own prompt is showing. */
+  isOpen: boolean
+  /** Between `pushStart` and `pushStop`: someone to register for. */
+  isActive: boolean
+}
+
+export type PushPromptType = {
+  create(entity: PushPromptEntity, payload?: unknown, api?: Api): void
+  /** Checks the permission: registers if granted, else opens the prompt. */
+  pushStart(entity: PushPromptEntity, payload?: unknown, api?: Api): void
+  /** Closes the prompt. */
+  pushStop(entity: PushPromptEntity): void
+  /** The prompt's yes: brings up the system's dialog. */
+  pushAsk(entity: PushPromptEntity, payload?: unknown, api?: Api): void
+  /** The prompt's no, remembered on this device. */
+  pushDecline(entity: PushPromptEntity): void
+  [handler: string]: unknown
+}
+
+/** The type that asks a device for pushes and keeps it registered. */
+export declare function createPushPrompt(
+  config: PushPromptConfig,
+): PushPromptType