@doscientos/pwa 0.1.2

package/README.md

@@ -0,0 +1,32 @@
+# @doscientos/pwa
+
+Reusable PWA installation primitives. It shares safe browser detection,
+installation state and service-worker registration without imposing a UI,
+manifest or caching strategy on applications.
+
+## Exports
+
+- `@doscientos/pwa/core`: browser-safe detection, dismissal storage and
+  `registerPwaServiceWorker`.
+- `@doscientos/pwa/react`: `usePwaInstallPrompt`, a headless React hook.
+
+Each app owns its manifest, icons, `public/sw.js`, cache name and cache policy.
+Never cache API, authentication or user-specific responses in a shared default.
+
+## React example
+
+Use `usePwaInstallPrompt({ storageKey: 'product:pwa-dismissed' })` and render
+your own design-system UI from its `visible`, `isIos`, `pending`, `install` and
+`dismiss` values. Register the worker once from the app shell with
+`registerPwaServiceWorker()`.
+
+## Publishing
+
+Run `npm run check` and `npm pack --dry-run` before publishing. Every regular
+commit to `main` publishes the next patch version and creates its tag
+automatically. To publish a minor or major, edit the `version` in
+`package.json` before pushing; the workflow publishes that exact version and
+continues patch releases from it. Configure npm Trusted Publishing for
+`doscientos-es/pwa`, workflow
+`.github/workflows/publish.yml`, and GitHub environment `npm-production`; no
+registry token is stored in the repository.

package/core.d.ts

@@ -0,0 +1,30 @@
+export type PwaInstallAvailability = {
+  isDismissed: boolean
+  isIos: boolean
+  isStandalone: boolean
+  canPrompt: boolean
+}
+
+export type PwaEnvironment = Pick<PwaInstallAvailability, 'isIos' | 'isStandalone'>
+
+export type PwaInstallPromptEvent = Event & {
+  prompt: () => Promise<void>
+  userChoice: Promise<{ outcome: 'accepted' | 'dismissed' }>
+}
+
+export declare function detectPwaEnvironment(options?: {
+  windowRef?: Window
+  navigatorRef?: Navigator
+}): PwaEnvironment
+export declare function shouldOfferPwaInstallation(availability: PwaInstallAvailability): boolean
+export declare function readPwaDismissal(storageKey: string, storage?: Storage): boolean
+export declare function persistPwaDismissal(storageKey: string, storage?: Storage): void
+export declare function registerPwaServiceWorker(options?: {
+  scriptUrl?: string
+  updateViaCache?: ServiceWorkerUpdateViaCache
+  onError?: (error: unknown) => void
+  onRegistered?: (registration: ServiceWorkerRegistration) => void
+  windowRef?: Window
+  navigatorRef?: Navigator
+  documentRef?: Document
+}): () => void

package/core.js

@@ -0,0 +1,75 @@
+const noOperation = () => undefined
+
+/** Returns browser capabilities without accessing globals during SSR. */
+export function detectPwaEnvironment({
+  windowRef = globalThis.window,
+  navigatorRef = globalThis.navigator,
+} = {}) {
+  if (!windowRef || !navigatorRef) return { isIos: false, isStandalone: false }
+
+  const isStandalone =
+    windowRef.matchMedia?.('(display-mode: standalone)').matches === true ||
+    navigatorRef.standalone === true
+  const isIos =
+    /iPad|iPhone|iPod/.test(navigatorRef.userAgent ?? '') ||
+    (navigatorRef.platform === 'MacIntel' && (navigatorRef.maxTouchPoints ?? 0) > 1)
+
+  return { isIos, isStandalone }
+}
+
+export function shouldOfferPwaInstallation({ isDismissed, isIos, isStandalone, canPrompt }) {
+  return !isStandalone && !isDismissed && (isIos || canPrompt)
+}
+
+export function readPwaDismissal(storageKey, storage = globalThis.localStorage) {
+  try {
+    return storage?.getItem(storageKey) === '1'
+  } catch {
+    return false
+  }
+}
+
+export function persistPwaDismissal(storageKey, storage = globalThis.localStorage) {
+  try {
+    storage?.setItem(storageKey, '1')
+  } catch {
+    // A prompt remains dismissible when storage is unavailable.
+  }
+}
+
+/**
+ * Registers an app-owned worker after load. Cache strategy remains in the app's
+ * service worker and is never inferred or shared by this package.
+ */
+export function registerPwaServiceWorker({
+  scriptUrl = '/sw.js',
+  updateViaCache = 'none',
+  onError = noOperation,
+  onRegistered = noOperation,
+  windowRef = globalThis.window,
+  navigatorRef = globalThis.navigator,
+  documentRef = globalThis.document,
+} = {}) {
+  const serviceWorker = navigatorRef?.serviceWorker
+  if (!windowRef || !documentRef || !serviceWorker?.register) return noOperation
+
+  let disposed = false
+  const register = () => {
+    void serviceWorker
+      .register(scriptUrl, { updateViaCache })
+      .then((registration) => {
+        if (!disposed) onRegistered(registration)
+      })
+      .catch((error) => {
+        if (!disposed) onError(error)
+      })
+  }
+
+  if (documentRef.readyState === 'complete') register()
+  else windowRef.addEventListener('load', register, { once: true })
+
+  return () => {
+    disposed = true
+    windowRef.removeEventListener('load', register)
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@doscientos/pwa",
+  "version": "0.1.2",
+  "private": false,
+  "description": "Safe, framework-aware PWA installation primitives for Doscientos applications.",
+  "license": "MIT",
+  "author": "Doscientos <dev@doscientos.es>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/doscientos-es/pwa.git"
+  },
+  "homepage": "https://github.com/doscientos-es/pwa#readme",
+  "bugs": {
+    "url": "https://github.com/doscientos-es/pwa/issues"
+  },
+  "files": [
+    "*.d.ts",
+    "*.js",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./core": {
+      "types": "./core.d.ts",
+      "import": "./core.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "import": "./react.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "node --test test/core.test.mjs",
+    "prepublishOnly": "npm run check",
+    "version:major": "npm version major --no-git-tag-version",
+    "version:minor": "npm version minor --no-git-tag-version",
+    "version:patch": "npm version patch --no-git-tag-version"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0 <20"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "packageManager": "pnpm@9.15.2"
+}

package/react.d.ts

@@ -0,0 +1,10 @@
+export type PwaInstallChoice = { outcome: 'accepted' | 'dismissed' }
+
+export declare function usePwaInstallPrompt(options: { storageKey: string }): {
+  isIos: boolean
+  isStandalone: boolean
+  visible: boolean
+  pending: boolean
+  dismiss: () => void
+  install: () => Promise<PwaInstallChoice | null>
+}

package/react.js

@@ -0,0 +1,61 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+
+import {
+  detectPwaEnvironment,
+  persistPwaDismissal,
+  readPwaDismissal,
+  shouldOfferPwaInstallation,
+} from './core.js'
+
+/** React adapter for the native install event; it intentionally renders no UI. */
+export function usePwaInstallPrompt({ storageKey } = {}) {
+  if (!storageKey) throw new Error('usePwaInstallPrompt requires a storageKey')
+
+  const [installEvent, setInstallEvent] = useState(null)
+  const [dismissed, setDismissed] = useState(true)
+  const [environment, setEnvironment] = useState({ isIos: false, isStandalone: true })
+  const [pending, setPending] = useState(false)
+
+  useEffect(() => {
+    setEnvironment(detectPwaEnvironment())
+    setDismissed(readPwaDismissal(storageKey))
+    const onBeforeInstallPrompt = (event) => {
+      event.preventDefault()
+      setInstallEvent(event)
+    }
+    window.addEventListener('beforeinstallprompt', onBeforeInstallPrompt)
+    return () => window.removeEventListener('beforeinstallprompt', onBeforeInstallPrompt)
+  }, [storageKey])
+
+  const dismiss = useCallback(() => {
+    persistPwaDismissal(storageKey)
+    setDismissed(true)
+  }, [storageKey])
+
+  const install = useCallback(async () => {
+    if (!installEvent) return null
+    setPending(true)
+    try {
+      await installEvent.prompt()
+      const choice = await installEvent.userChoice
+      if (choice.outcome === 'accepted')
+        setEnvironment((current) => ({ ...current, isStandalone: true }))
+      setInstallEvent(null)
+      return choice
+    } finally {
+      setPending(false)
+    }
+  }, [installEvent])
+
+  const visible = useMemo(
+    () =>
+      shouldOfferPwaInstallation({
+        ...environment,
+        isDismissed: dismissed,
+        canPrompt: installEvent !== null,
+      }),
+    [dismissed, environment, installEvent],
+  )
+
+  return { ...environment, dismiss, install, pending, visible }
+}