@inglorious/web 6.10.2 → 6.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "6.10.2",
+  "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": [
@@ -41,6 +41,10 @@
       "types": "./types/decorators/with-error-boundary.d.ts",
       "import": "./src/decorators/with-error-boundary/index.js"
     },
+    "./decorators/with-live-reload": {
+      "types": "./types/decorators/with-live-reload.d.ts",
+      "import": "./src/decorators/with-live-reload/index.js"
+    },
     "./decorators/with-throttle": {
       "types": "./types/decorators/with-throttle.d.ts",
       "import": "./src/decorators/with-throttle/index.js"
@@ -62,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"
@@ -123,7 +131,7 @@
     "vitest": "^5.0.0"
   },
   "engines": {
-    "node": ">= 22"
+    "node": ">= 26"
   },
   "scripts": {
     "format": "prettier --write .",

package/src/decorators/with-live-reload/index.js

@@ -0,0 +1,113 @@
+import { debounce } from "@inglorious/utils/functions"
+
+const DEFAULT_DELAY = 300
+
+// Every live entity's reload, across all the types that use the decorator, so
+// one listener can reload them all when the page comes back into view.
+const reloads = new Set()
+let isWatchingVisibility = false
+
+/**
+ * Keeps an entity in step with a backend: whenever one of the `tables` it
+ * reads changes, it reloads, by notifying its own `event` (default `"load"`).
+ * There is no matching of which rows changed: a change to a table the entity
+ * reads is enough. That costs a reload now and then, and spares every type
+ * the rules that decide whether a change concerns it, which is where live
+ * data goes wrong.
+ *
+ * - `source` delivers the changes: `subscribe(table, onChange)` returns an
+ *   unsubscribe function. `@inglorious/supabase` has one for Supabase
+ *   Realtime.
+ * - `payload(entity, api)` is what the event carries, such as the id of the
+ *   record the entity shows.
+ * - `isLive(entity, api)` says whether the entity is on screen. A change
+ *   while it is not is skipped: it loads when it opens anyway. Defaults to
+ *   always.
+ * - `delay` (default 300 ms) gathers a burst of changes into one reload.
+ *
+ * It also reloads every live entity when the page comes back into view: a
+ * phone that put the app in the background may have dropped the connection,
+ * and the changes with it.
+ *
+ * IMPORTANT: changes arrive long after the handler that subscribed has
+ * returned, when its `entity` draft is revoked. So only the entity's `id` is
+ * held, and the live entity is read from `api.getEntity(id)` when a change
+ * comes.
+ *
+ * @param {Object} config
+ * @param {{ subscribe(table: string, onChange: () => void): () => void }} config.source
+ * @param {string[]} config.tables - The tables the entity reads.
+ * @param {string} [config.event] - The event that reloads it.
+ * @param {(entity: Object, api: Object) => unknown} [config.payload]
+ * @param {(entity: Object, api: Object) => boolean} [config.isLive]
+ * @param {number} [config.delay]
+ *
+ * @example
+ * const types = {
+ *   Inbox: [
+ *     Inbox,
+ *     withLiveReload({
+ *       source: realtimeSource(supabase),
+ *       tables: ["messages"],
+ *       payload: (entity) => entity.folderId,
+ *     }),
+ *   ],
+ * }
+ */
+export function withLiveReload({
+  source,
+  tables,
+  event = "load",
+  payload,
+  isLive = () => true,
+  delay = DEFAULT_DELAY,
+}) {
+  return (type) => {
+    // entity id -> what to cancel when it goes
+    const subscriptions = new Map()
+
+    function stop(id) {
+      const subscription = subscriptions.get(id)
+      if (!subscription) return
+      subscription.reload.cancel()
+      subscription.unsubscribes.forEach((unsubscribe) => unsubscribe())
+      reloads.delete(subscription.reload)
+      subscriptions.delete(id)
+    }
+
+    return {
+      create(entity, createPayload, api) {
+        type.create?.(entity, createPayload, api)
+
+        const id = entity.id // capture the primitive now, while the draft is live
+        stop(id)
+        const reload = debounce(() => {
+          const live = api.getEntity(id) // fresh, live reference
+          if (!live || !isLive(live, api)) return
+          api.notify(`#${id}:${event}`, payload?.(live, api))
+        }, delay)
+
+        subscriptions.set(id, {
+          reload,
+          unsubscribes: tables.map((table) => source.subscribe(table, reload)),
+        })
+        reloads.add(reload)
+        watchVisibility()
+      },
+
+      destroy(entity, destroyPayload, api) {
+        stop(entity.id)
+        type.destroy?.(entity, destroyPayload, api)
+      },
+    }
+  }
+}
+
+function watchVisibility() {
+  if (isWatchingVisibility || typeof document === "undefined") return
+  isWatchingVisibility = true
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState !== "visible") return
+    reloads.forEach((reload) => reload())
+  })
+}

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/decorators/with-live-reload.d.ts

@@ -0,0 +1,30 @@
+import { Api } from "../mount"
+
+/** Delivers a backend's changes, one table at a time. */
+export interface LiveSource {
+  /** Calls `onChange` on every change to `table`; returns the unsubscribe. */
+  subscribe(table: string, onChange: () => void): () => void
+}
+
+export interface LiveReloadConfig<TEntity = any> {
+  source: LiveSource
+  /** The tables the entity reads. */
+  tables: string[]
+  /** The event that reloads the entity. Defaults to `"load"`. */
+  event?: string
+  /** What the event carries, such as the id of the record the entity shows. */
+  payload?: (entity: TEntity, api: Api) => unknown
+  /** Whether the entity is on screen. Defaults to always. */
+  isLive?: (entity: TEntity, api: Api) => boolean
+  /** Gathers a burst of changes into one reload. Defaults to 300 ms. */
+  delay?: number
+}
+
+export interface LiveReloadBehavior {
+  create: (entity: any, payload?: any, api?: Api) => void
+  destroy: (entity: any, payload?: any, api?: Api) => void
+}
+
+export declare function withLiveReload<TEntity = any>(
+  config: LiveReloadConfig<TEntity>,
+): <T extends Record<string, any>>(type: T) => LiveReloadBehavior

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