@12-apps/ui 1.6.0 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "license": "MIT",
   "packageManager": "pnpm@9.0.0",
   "type": "module",
@@ -194,7 +194,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@12-apps/forms-core": "^1.5.0",
+    "@12-apps/forms-core": "^1.5.1",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@monaco-editor/react": "^4.7.0",
@@ -209,8 +209,8 @@
     "recharts": "^3.5.1"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.6.0",
-    "@12-apps/typescript-config": "^1.6.0",
+    "@12-apps/eslint-config": "^1.6.1",
+    "@12-apps/typescript-config": "^1.6.1",
     "@playwright/test": "^1.55.0",
     "@storybook/addon-docs": "^9.1.10",
     "@storybook/addon-links": "^9.1.10",

package/src/components/utility/InstallPrompt/InstallPrompt.earlyCapture.ts

@@ -0,0 +1,117 @@
+import type { BeforeInstallPromptEvent, PwaInstallStash } from './InstallPrompt.types';
+
+/**
+ * Holds `beforeinstallprompt` from before the app exists.
+ *
+ * `usePwaInstall` cannot attach its own listener early enough, and no React
+ * hook can. Chromium fires the event once, during initial page load, the
+ * moment it has a manifest and a registered worker — which in a real app is
+ * before hydration, and often before the chunk containing the component has
+ * even been downloaded. A listener registered in an effect is not late by
+ * milliseconds; it can be late by entire navigations. Nothing calls
+ * `preventDefault()` in time, the browser keeps the event, and the page can
+ * never ask again.
+ *
+ * So the capture has to live outside React, and the host has to install it as
+ * the very first thing the document does. Two supported ways, in order of
+ * reliability:
+ *
+ * 1. An inline `<script>` in `<head>`, which beats a deferred module bundle:
+ *
+ *        <script>
+ *          window.addEventListener('beforeinstallprompt', function (e) {
+ *            e.preventDefault();
+ *            var s = (window.__pwaInstall = window.__pwaInstall || {});
+ *            s.event = e; s.firedAt = Date.now();
+ *            window.dispatchEvent(new Event('pwa-install-available'));
+ *          });
+ *        </script>
+ *
+ * 2. `capturePwaInstallEvent()` as the first statement of the entry module,
+ *    before `createRoot`. Simpler to wire and correct in most apps, but a
+ *    module is still deferred, so a very early event can outrun it.
+ *
+ * Both write the same shape, so the hook does not care which was used.
+ */
+
+/** Property on `window` holding the captured event. Shared with the inline snippet. */
+export const PWA_INSTALL_STASH_KEY = '__pwaInstall';
+
+/** Fired after a capture, so an app already running can adopt the event. */
+export const PWA_INSTALL_AVAILABLE_EVENT = 'pwa-install-available';
+
+type StashHost = Window & { [PWA_INSTALL_STASH_KEY]?: PwaInstallStash };
+
+/** The stash, or `null` when no capture ever ran (SSR, or a host that skipped wiring). */
+export const readPwaInstallStash = (): PwaInstallStash | null => {
+  if (typeof window === 'undefined') return null;
+  return (window as StashHost)[PWA_INSTALL_STASH_KEY] ?? null;
+};
+
+const ensureStash = (): PwaInstallStash => {
+  const host = window as StashHost;
+  host[PWA_INSTALL_STASH_KEY] ??= { event: null, firedAt: null, installedAt: null };
+  return host[PWA_INSTALL_STASH_KEY];
+};
+
+/**
+ * The teardown for the capture currently running, so `resetPwaInstallStash`
+ * can unwind completely. Held here rather than on the stash because it must
+ * survive the stash being deleted, and because it must never be serialised
+ * into the diagnostic payload.
+ */
+let activeTeardown: (() => void) | null = null;
+
+/**
+ * Starts capturing. Returns a teardown, and is safe to call twice — a second
+ * call is a no-op rather than a duplicate listener, so a host that wires both
+ * the inline snippet and this function does not double-handle the event.
+ */
+export const capturePwaInstallEvent = (): (() => void) => {
+  if (typeof window === 'undefined') return () => undefined;
+
+  const stash = ensureStash();
+  if (stash.capturing === true) return () => undefined;
+  stash.capturing = true;
+
+  const onBeforeInstall = (event: Event): void => {
+    // The line the whole component depends on. Without it the browser owns the
+    // event, shows at most its own mini-infobar, and discards the handle.
+    event.preventDefault();
+    stash.event = event as BeforeInstallPromptEvent;
+    stash.firedAt = Date.now();
+    window.dispatchEvent(new Event(PWA_INSTALL_AVAILABLE_EVENT));
+  };
+
+  const onInstalled = (): void => {
+    stash.installedAt = Date.now();
+    stash.event = null;
+  };
+
+  window.addEventListener('beforeinstallprompt', onBeforeInstall);
+  window.addEventListener('appinstalled', onInstalled);
+
+  const teardown = () => {
+    window.removeEventListener('beforeinstallprompt', onBeforeInstall);
+    window.removeEventListener('appinstalled', onInstalled);
+    stash.capturing = false;
+    if (activeTeardown === teardown) activeTeardown = null;
+  };
+
+  activeTeardown = teardown;
+  return teardown;
+};
+
+/**
+ * Returns the page to its pre-capture state: listeners removed, stash gone.
+ *
+ * Exists for tests and stories, which need a clean page per case. It unwinds
+ * the listeners as well as the data, because a leaked capture from a previous
+ * case would go on suppressing events that the next case expects to observe.
+ */
+export const resetPwaInstallStash = (): void => {
+  if (typeof window === 'undefined') return;
+  activeTeardown?.();
+  activeTeardown = null;
+  delete (window as StashHost)[PWA_INSTALL_STASH_KEY];
+};

package/src/components/utility/InstallPrompt/InstallPrompt.md

@@ -85,6 +85,54 @@ raised from a timer or an effect.
 All copy defaults to English and every string is a prop — this package is
 locale-neutral and the consuming app supplies its own wording.
 
+## Wiring the capture
+
+**Required on Chromium.** Without it this component can never offer an install,
+and it will fail silently — no error, no warning, just an affordance that never
+appears.
+
+Chromium fires `beforeinstallprompt` once, during page load, as soon as it has a
+manifest and a registered worker. That is before hydration, and in a code-split
+app it can be before the chunk holding this component has been downloaded at
+all. No React hook can attach a listener in time, and the event is not reissued
+on request. So the capture has to run outside React, and first.
+
+Paste this into `<head>`, above the app bundle. A classic inline script is the
+only thing guaranteed to beat a deferred module:
+
+```html
+<script>
+  (function () {
+    var stash = (window.__pwaInstall = { event: null, firedAt: null, installedAt: null });
+    window.addEventListener('beforeinstallprompt', function (event) {
+      event.preventDefault();
+      stash.event = event;
+      stash.firedAt = Date.now();
+      window.dispatchEvent(new Event('pwa-install-available'));
+    });
+    window.addEventListener('appinstalled', function () {
+      stash.installedAt = Date.now();
+      stash.event = null;
+    });
+  })();
+</script>
+```
+
+Or call `capturePwaInstallEvent()` as the first statement of your entry module,
+before `createRoot`. Simpler to wire, but a module is still deferred, so a very
+early event can outrun it. Doing both is safe — the capture is idempotent.
+
+```ts
+import { capturePwaInstallEvent } from '@12-apps/ui/utility/InstallPrompt';
+
+capturePwaInstallEvent();
+```
+
+`readPwaInstallStash()` exposes what was captured (`event`, `firedAt`,
+`installedAt`), which is worth logging when the prompt does not appear:
+`firedAt` set with no visible affordance means something downstream suppressed
+it, whereas an absent stash means the wiring above is missing.
+
 ## Hook API
 
 `usePwaInstall(options)` returns:
@@ -107,7 +155,7 @@ locale-neutral and the consuming app supplies its own wording.
 - **Storage failures are swallowed.** `localStorage` throws rather than returning
   `null` in Safari private mode and wherever cookies are blocked; an uncaught throw
   would break the page on exactly the browsers this component serves.
-- **A missed first event recovers on its own.** The listener attaches on mount,
-  which can be after a cold-load event. Chromium re-fires on navigation and on
-  re-evaluation of the criteria. A host that needs the very first one can capture
-  it in its HTML entry point and re-dispatch it once the app has mounted.
+- **A missed event does NOT recover.** Chromium fires `beforeinstallprompt` once
+  and will not reissue it on request, so a listener that attaches on mount has
+  already lost. This is why "Wiring the capture" above is a requirement rather
+  than an optimisation.

package/src/components/utility/InstallPrompt/InstallPrompt.types.ts

@@ -15,6 +15,25 @@ export interface BeforeInstallPromptEvent extends Event {
   prompt: () => Promise<void>;
 }
 
+/**
+ * What the pre-React capture left on `window` for the hook to pick up.
+ *
+ * This is the handoff between code that runs before the app exists and code
+ * that runs inside it. Written either by `capturePwaInstallEvent()` or by the
+ * equivalent inline snippet in the host's HTML, and read on mount — the event
+ * has almost always fired long before any component is alive to hear it.
+ */
+export interface PwaInstallStash {
+  /** The held event, or `null` if none has fired or it was already spent. */
+  event: BeforeInstallPromptEvent | null;
+  /** When it was captured. Diagnostic: proves the capture ran and the browser offered. */
+  firedAt: number | null;
+  /** When `appinstalled` was seen, if it arrived before the app mounted. */
+  installedAt: number | null;
+  /** Guards against a host wiring both the inline snippet and the function. */
+  capturing?: boolean;
+}
+
 /**
  * How — or whether — this browser can install the app.
  *

package/src/components/utility/InstallPrompt/index.ts

@@ -1,10 +1,18 @@
 export { InstallPrompt } from './InstallPrompt';
 export { usePwaInstall } from './usePwaInstall';
+export {
+  capturePwaInstallEvent,
+  readPwaInstallStash,
+  resetPwaInstallStash,
+  PWA_INSTALL_AVAILABLE_EVENT,
+  PWA_INSTALL_STASH_KEY,
+} from './InstallPrompt.earlyCapture';
 export type {
   BeforeInstallPromptEvent,
   InstallOutcome,
   InstallPlatform,
   InstallPromptProps,
   PwaInstallState,
+  PwaInstallStash,
   UsePwaInstallOptions,
 } from './InstallPrompt.types';

package/src/components/utility/InstallPrompt/usePwaInstall.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 
+import { PWA_INSTALL_AVAILABLE_EVENT, readPwaInstallStash } from './InstallPrompt.earlyCapture';
 import {
   DEFAULT_DISMISS_DAYS,
   DEFAULT_STORAGE_KEY,
@@ -50,7 +51,9 @@ const useInstalledState = (onInstalled?: () => void) => {
   }, [onInstalled]);
 
   useEffect(() => {
-    setIsInstalled(isStandaloneDisplay());
+    // `appinstalled` can also land before the app mounts, so the stash is
+    // consulted for the same reason the deferred event is.
+    setIsInstalled(isStandaloneDisplay() || readPwaInstallStash()?.installedAt != null);
 
     const markInstalled = () => {
       setIsInstalled(true);
@@ -65,29 +68,54 @@ const useInstalledState = (onInstalled?: () => void) => {
 };
 
 /**
- * Captures and holds the deferred `beforeinstallprompt` event.
+ * Holds the deferred `beforeinstallprompt` event.
  *
- * The listener is attached on mount, which is normally AFTER the browser would
- * have fired the event on a cold load. Chromium re-fires it on navigation and
- * on re-evaluation of the install criteria, so a missed first event resolves
- * itself; a host that needs the very first one can attach an early capture in
- * its HTML entry point and re-dispatch it.
+ * The stash written by `capturePwaInstallEvent` is the PRIMARY source, not a
+ * fallback. Chromium fires the event once, during initial page load; a
+ * listener attached in an effect runs after hydration and, when the component
+ * is code-split, after a download that may not happen until a later route. In
+ * a real browser it essentially never catches the event, and the event is not
+ * reissued on request — so a hook that relies on its own listener reports
+ * "cannot install" forever on the one platform that can.
+ *
+ * The live listeners below therefore cover only the narrow case they can
+ * actually serve: a browser re-evaluating installability while the app is
+ * already running, and a host that never wired the capture at all.
  */
 const useDeferredPrompt = () => {
   const deferredRef = useRef<BeforeInstallPromptEvent | null>(null);
   const [promptReady, setPromptReady] = useState(false);
 
   useEffect(() => {
+    const hold = (event: BeforeInstallPromptEvent) => {
+      deferredRef.current = event;
+      setPromptReady(true);
+    };
+
+    // Whatever fired before this component existed.
+    const held = readPwaInstallStash()?.event;
+    if (held) hold(held);
+
+    // The capture rang the bell after mount: adopt what it is holding.
+    const adopt = () => {
+      const fresh = readPwaInstallStash()?.event;
+      if (fresh) hold(fresh);
+    };
+
     const capture = (event: Event) => {
       // Without preventDefault the browser owns the event and the handle dies
-      // with it — this is the line that makes an in-page install button possible.
+      // with it. The capture has normally done this already; repeating it is
+      // harmless and keeps the hook correct on a host that skipped wiring.
       event.preventDefault();
-      deferredRef.current = event as BeforeInstallPromptEvent;
-      setPromptReady(true);
+      hold(event as BeforeInstallPromptEvent);
     };
 
+    window.addEventListener(PWA_INSTALL_AVAILABLE_EVENT, adopt);
     window.addEventListener('beforeinstallprompt', capture);
-    return () => window.removeEventListener('beforeinstallprompt', capture);
+    return () => {
+      window.removeEventListener(PWA_INSTALL_AVAILABLE_EVENT, adopt);
+      window.removeEventListener('beforeinstallprompt', capture);
+    };
   }, []);
 
   const clearPrompt = useCallback(() => {