@kestack/web-platform 0.0.0-stage → 0.0.0

package/src/pwa/client/status/status.ts

@@ -0,0 +1,155 @@
+import * as Data from 'effect/Data';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Schedule from 'effect/Schedule';
+import * as SubscriptionRef from 'effect/SubscriptionRef';
+import { listen } from '../../browser/dom-events.js';
+import type { UpdateConfig } from '../../shared/config/index.js';
+import { sendCommand } from '../commands/index.js';
+
+/**
+ * The page's one view of its service worker.
+ * - `Unsupported`: no service workers here, or the PWA is off in this build.
+ * - `Installing`: first visit; the worker is saving this build's files.
+ * - `Ready`: the worker is active; the app works offline.
+ * - `UpdateReady`: a newer build is downloaded and waiting.
+ * - `Updating`: the update was accepted; every page is about to reload.
+ */
+export type PwaStatus = Data.TaggedEnum<{
+  Unsupported: {};
+  Installing: {};
+  Ready: {};
+  UpdateReady: {};
+  Updating: {};
+}>;
+export const PwaStatus = Data.taggedEnum<PwaStatus>();
+
+export interface StatusService {
+  readonly status: SubscriptionRef.SubscriptionRef<PwaStatus>;
+  readonly checkForUpdate: Effect.Effect<void>;
+  readonly applyUpdate: Effect.Effect<void>;
+}
+
+const unsupported = Effect.map(
+  SubscriptionRef.make<PwaStatus>(PwaStatus.Unsupported()),
+  (status): StatusService => ({
+    status,
+    checkForUpdate: Effect.void,
+    applyUpdate: Effect.void,
+  }),
+);
+
+/**
+ * Status for one registration, from the browser's own service worker events;
+ * the worker is never asked. Checks for an update on load, on focus and
+ * visibility, and every `checkIntervalMinutes`. Reloads only on
+ * `controllerchange` after an update activates, in every open page.
+ */
+export const makeStatus = (
+  config: UpdateConfig,
+  registration: Option.Option<ServiceWorkerRegistration>,
+) =>
+  Option.match(registration, {
+    onNone: () => unsupported,
+    onSome: (registration) => makeRegisteredStatus(config, registration),
+  });
+
+const makeRegisteredStatus = Effect.fnUntraced(function* (
+  config: UpdateConfig,
+  registration: ServiceWorkerRegistration,
+) {
+  const container = navigator.serviceWorker;
+  // A waiting worker is an update only when a previous version controls the page.
+  const hasUpdate = () =>
+    registration.waiting !== null && container.controller !== null;
+  const initial = (): PwaStatus =>
+    hasUpdate()
+      ? PwaStatus.UpdateReady()
+      : registration.active === null
+        ? PwaStatus.Installing()
+        : PwaStatus.Ready();
+
+  const status = yield* SubscriptionRef.make<PwaStatus>(initial());
+  const set = (next: PwaStatus) =>
+    Effect.runSync(
+      SubscriptionRef.update(status, (current) =>
+        current._tag === 'Updating' ? current : next,
+      ),
+    );
+
+  const watchInstalling = (worker: ServiceWorker | null) =>
+    worker?.addEventListener('statechange', () => {
+      if (worker.state === 'installed' && hasUpdate()) {
+        set(PwaStatus.UpdateReady());
+      } else if (worker.state === 'redundant' && registration.active === null) {
+        // The first install failed (e.g. a Precache download); the next load retries.
+        set(PwaStatus.Unsupported());
+      }
+    });
+
+  let checking = false;
+  const checkForUpdate = Effect.gen(function* () {
+    const current = yield* SubscriptionRef.get(status);
+    if (checking || current._tag !== 'Ready') return;
+    checking = true;
+    yield* Effect.tryPromise(() => registration.update()).pipe(
+      Effect.ignore,
+      Effect.ensuring(Effect.sync(() => (checking = false))),
+    );
+    if (hasUpdate()) set(PwaStatus.UpdateReady());
+  });
+
+  const applyUpdate = Effect.gen(function* () {
+    const waiting = registration.waiting;
+    const accepted = yield* SubscriptionRef.modify(status, (current) =>
+      current._tag === 'UpdateReady' && waiting !== null
+        ? [true, PwaStatus.Updating()]
+        : [false, current],
+    );
+    if (!accepted || waiting === null) return;
+    const reply = yield* sendCommand(waiting, 'SKIP_WAITING');
+    if (Option.isNone(reply) || reply.value.type === 'FAILED') {
+      yield* Effect.logWarning(
+        'pwa-toolkit: waiting worker did not activate',
+        reply,
+      );
+      yield* SubscriptionRef.set(status, PwaStatus.UpdateReady());
+    }
+  });
+
+  // First install takes control of a page with no previous controller: Ready, no reload.
+  let hadController = container.controller !== null;
+  let reloading = false;
+  yield* listen(container, 'controllerchange', () => {
+    if (!hadController) {
+      hadController = true;
+      set(PwaStatus.Ready());
+      return;
+    }
+    if (reloading) return;
+    reloading = true;
+    Effect.runSync(SubscriptionRef.set(status, PwaStatus.Updating()));
+    window.location.reload();
+  });
+
+  watchInstalling(registration.installing);
+  yield* listen(registration, 'updatefound', () =>
+    watchInstalling(registration.installing),
+  );
+
+  const runCheck = () => void Effect.runFork(checkForUpdate);
+  yield* listen(window, 'focus', runCheck);
+  yield* listen(document, 'visibilitychange', () => {
+    if (document.visibilityState === 'visible') runCheck();
+  });
+  yield* Effect.forkScoped(
+    checkForUpdate.pipe(
+      Effect.repeat(
+        Schedule.spaced(Duration.minutes(config.checkIntervalMinutes)),
+      ),
+    ),
+  );
+
+  return { status, checkForUpdate, applyUpdate } satisfies StatusService;
+});

package/src/pwa/extras/display-mode/display-mode.ts

@@ -0,0 +1,64 @@
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as SubscriptionRef from 'effect/SubscriptionRef';
+import { isBrowser, listen } from '../../browser/dom-events.js';
+import { useSubscriptionRef } from '../../browser/subscription-ref.js';
+import { lazyService } from '../lazy-service/index.js';
+
+export type DisplayModeValue =
+  | 'browser'
+  | 'standalone'
+  | 'minimal-ui'
+  | 'fullscreen'
+  | 'window-controls-overlay';
+
+// Most specific first: a window-controls-overlay app also matches nothing else.
+const INSTALLED_MODES = [
+  'fullscreen',
+  'window-controls-overlay',
+  'standalone',
+  'minimal-ui',
+] as const;
+
+const query = (mode: DisplayModeValue) =>
+  window.matchMedia(`(display-mode: ${mode})`);
+
+/** `navigator.standalone` covers iOS Safari, which has no display-mode media query for home-screen apps before 16.4. */
+export const readDisplayMode = (): DisplayModeValue => {
+  if (!isBrowser()) return 'browser';
+  if (typeof window.matchMedia === 'function') {
+    const match = INSTALLED_MODES.find((mode) => query(mode).matches);
+    if (match !== undefined) return match;
+  }
+  return (navigator as { readonly standalone?: boolean }).standalone === true
+    ? 'standalone'
+    : 'browser';
+};
+
+/** How the page is shown: in a browser tab or as an installed app. */
+export class DisplayMode extends Context.Service<
+  DisplayMode,
+  { readonly mode: SubscriptionRef.SubscriptionRef<DisplayModeValue> }
+>()('@kestack/web-platform/pwa/DisplayMode') {
+  static readonly layer: Layer.Layer<DisplayMode> = Layer.effect(
+    this,
+    Effect.gen(function* () {
+      const mode = yield* SubscriptionRef.make(readDisplayMode());
+      if (isBrowser() && typeof window.matchMedia === 'function') {
+        const refresh = () =>
+          Effect.runSync(SubscriptionRef.set(mode, readDisplayMode()));
+        for (const value of INSTALLED_MODES) {
+          yield* listen(query(value), 'change', refresh);
+        }
+      }
+      return { mode };
+    }),
+  );
+}
+
+const useDisplayModeService = lazyService(DisplayMode, DisplayMode.layer);
+
+/** The display mode; `'browser'` during SSR and until known. */
+export const useDisplayMode = (): DisplayModeValue =>
+  useSubscriptionRef(useDisplayModeService()?.mode, 'browser');

package/src/pwa/extras/display-mode/index.ts

@@ -0,0 +1,6 @@
+export {
+  DisplayMode,
+  type DisplayModeValue,
+  readDisplayMode,
+  useDisplayMode,
+} from './display-mode.js';

package/src/pwa/extras/index.ts

@@ -0,0 +1,15 @@
+export {
+  DisplayMode,
+  type DisplayModeValue,
+  useDisplayMode,
+} from './display-mode/index.js';
+export {
+  Install,
+  InstallPrompt,
+  InstallState,
+  IosSteps,
+  isIosSafari,
+  useInstall,
+} from './install/index.js';
+export { OfflineIndicator, Online, useOnline } from './online/index.js';
+export { StoragePersistence, useStoragePersistence } from './storage/index.js';

package/src/pwa/extras/install/index.ts

@@ -0,0 +1,4 @@
+export { Install, InstallState, useInstall } from './install.js';
+export { IosSteps } from './install-content.js';
+export { InstallPrompt } from './install-prompt.js';
+export { isIosSafari } from './ios.js';

package/src/pwa/extras/install/install-content.tsx

@@ -0,0 +1,45 @@
+import { Button } from '#components/ui/button';
+import { ShareIcon, SquarePlusIcon } from '#lib/lucide';
+import type { ReactNode } from 'react';
+
+/** iOS Safari has no install API; the user adds the app from the Share sheet. */
+export const IosSteps = (): ReactNode => (
+  <ol className="flex flex-col gap-3 text-sm">
+    <li className="flex items-center gap-3">
+      <ShareIcon aria-hidden="true" className="size-5 shrink-0" />
+      <span>
+        Tap <strong className="font-medium">Share</strong> in the browser
+        toolbar.
+      </span>
+    </li>
+    <li className="flex items-center gap-3">
+      <SquarePlusIcon aria-hidden="true" className="size-5 shrink-0" />
+      <span>
+        Choose <strong className="font-medium">Add to Home Screen</strong>.
+      </span>
+    </li>
+  </ol>
+);
+
+/** Primary action last; on touch the buttons grow to a 44px hit area. */
+export const InstallActions = (props: {
+  readonly manual: boolean;
+  readonly onInstall: () => void;
+  readonly onDismiss: () => void;
+}): ReactNode => {
+  const size = 'min-h-11 touch-manipulation sm:min-h-0';
+  return props.manual ? (
+    <Button className={size} onClick={props.onDismiss}>
+      Got it
+    </Button>
+  ) : (
+    <>
+      <Button variant="ghost" className={size} onClick={props.onDismiss}>
+        Not now
+      </Button>
+      <Button className={size} onClick={props.onInstall}>
+        Install
+      </Button>
+    </>
+  );
+};

package/src/pwa/extras/install/install-dismissal.ts

@@ -0,0 +1,20 @@
+const KEY = 'pwa-toolkit:install-dismissed-at';
+const REMEMBER_MS = 30 * 24 * 60 * 60 * 1000;
+
+// localStorage throws in some private modes; then dismissal lasts for the page only.
+export const dismissedRecently = (now = Date.now()): boolean => {
+  try {
+    const at = Number(localStorage.getItem(KEY));
+    return at > 0 && now - at < REMEMBER_MS;
+  } catch {
+    return false;
+  }
+};
+
+export const rememberDismissal = (now = Date.now()): void => {
+  try {
+    localStorage.setItem(KEY, String(now));
+  } catch {
+    // see above
+  }
+};

package/src/pwa/extras/install/install-prompt.tsx

@@ -0,0 +1,93 @@
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from '#components/ui/card';
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+} from '#components/ui/sheet';
+import { type ReactNode, useId } from 'react';
+import { InstallActions, IosSteps } from './install-content.js';
+import { useInstall } from './install.js';
+import { useMediaQuery } from './media-query.js';
+
+/**
+ * Bottom sheet on small screens, a corner card on larger ones; manual steps
+ * on iOS Safari. Closing it any way counts as a dismissal (30 days).
+ */
+export const InstallPrompt = (props: {
+  readonly title?: string;
+  readonly description?: string;
+}): ReactNode => {
+  const { state, prompt, dismiss } = useInstall();
+  const compact = useMediaQuery('(max-width: 40rem)');
+  const titleId = useId();
+  if (state._tag !== 'Available' && state._tag !== 'ManualIos') return null;
+
+  const manual = state._tag === 'ManualIos';
+  const title = props.title ?? 'Install this app';
+  const description =
+    props.description ??
+    'Add it to your home screen for quick access, even offline.';
+  const actions = (
+    <InstallActions
+      manual={manual}
+      onInstall={() => void prompt()}
+      onDismiss={dismiss}
+    />
+  );
+
+  if (compact) {
+    return (
+      <Sheet open onOpenChange={(open) => !open && dismiss()}>
+        {/* No X: its tap target is under 44px, and the footer's
+            "Not now" / "Got it" already close the sheet. */}
+        <SheetContent
+          side="bottom"
+          showCloseButton={false}
+          className="rounded-t-2xl pb-[env(safe-area-inset-bottom)]"
+        >
+          <SheetHeader>
+            <SheetTitle>{title}</SheetTitle>
+            <SheetDescription>{description}</SheetDescription>
+          </SheetHeader>
+          {manual && (
+            <div className="px-4">
+              <IosSteps />
+            </div>
+          )}
+          <SheetFooter>{actions}</SheetFooter>
+        </SheetContent>
+      </Sheet>
+    );
+  }
+
+  // Not modal: an unasked-for invitation must not take focus from the page.
+  return (
+    <aside
+      aria-labelledby={titleId}
+      className="fixed right-[max(1rem,env(safe-area-inset-right))] bottom-[max(1rem,env(safe-area-inset-bottom))] z-50 w-full max-w-sm animate-in duration-200 ease-out fade-in slide-in-from-bottom-2 motion-reduce:animate-none"
+    >
+      <Card size="sm" className="shadow-lg">
+        <CardHeader>
+          <CardTitle id={titleId}>{title}</CardTitle>
+          <CardDescription>{description}</CardDescription>
+        </CardHeader>
+        {manual && (
+          <CardContent>
+            <IosSteps />
+          </CardContent>
+        )}
+        <CardFooter className="justify-end gap-2">{actions}</CardFooter>
+      </Card>
+    </aside>
+  );
+};

package/src/pwa/extras/install/install.ts

@@ -0,0 +1,134 @@
+import * as Context from 'effect/Context';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as SubscriptionRef from 'effect/SubscriptionRef';
+import { useMemo } from 'react';
+import { isBrowser, listen } from '../../browser/dom-events.js';
+import { useSubscriptionRef } from '../../browser/subscription-ref.js';
+import { readDisplayMode } from '../display-mode/index.js';
+import { lazyService } from '../lazy-service/index.js';
+import { dismissedRecently, rememberDismissal } from './install-dismissal.js';
+import { isIosSafari } from './ios.js';
+
+export type InstallState = Data.TaggedEnum<{
+  Unsupported: {};
+  Available: {};
+  ManualIos: {};
+  Installed: {};
+  Dismissed: {};
+}>;
+export const InstallState = Data.taggedEnum<InstallState>();
+
+/** Chromium's install event; not in the DOM lib. */
+interface BeforeInstallPromptEvent extends Event {
+  readonly prompt: () => Promise<void>;
+  readonly userChoice: Promise<{ readonly outcome: 'accepted' | 'dismissed' }>;
+}
+
+const initialState = (): InstallState => {
+  if (!isBrowser()) return InstallState.Unsupported();
+  if (readDisplayMode() !== 'browser') return InstallState.Installed();
+  if (dismissedRecently()) return InstallState.Dismissed();
+  if (isIosSafari(navigator)) return InstallState.ManualIos();
+  return InstallState.Unsupported();
+};
+
+/**
+ * Install Prompt state: adding the app to the home screen or dock. Captures
+ * `beforeinstallprompt` so the app decides when to ask. `prompt` still works
+ * after a dismissal; dismissal (remembered for 30 days) only hides the
+ * unsolicited Install Prompt.
+ */
+export class Install extends Context.Service<
+  Install,
+  {
+    readonly state: SubscriptionRef.SubscriptionRef<InstallState>;
+    readonly prompt: Effect.Effect<'accepted' | 'dismissed' | 'unavailable'>;
+    readonly dismiss: Effect.Effect<void>;
+  }
+>()('@kestack/web-platform/pwa/Install') {
+  static readonly layer: Layer.Layer<Install> = Layer.effect(
+    this,
+    Effect.gen(function* () {
+      const state = yield* SubscriptionRef.make(initialState());
+      let deferred: BeforeInstallPromptEvent | null = null;
+
+      const dismiss = Effect.sync(rememberDismissal).pipe(
+        Effect.andThen(
+          SubscriptionRef.update(state, (current) =>
+            current._tag === 'Installed' ? current : InstallState.Dismissed(),
+          ),
+        ),
+      );
+
+      if (isBrowser()) {
+        yield* listen(window, 'beforeinstallprompt', (event) => {
+          event.preventDefault();
+          deferred = event as BeforeInstallPromptEvent;
+          Effect.runSync(
+            SubscriptionRef.update(state, (current) =>
+              current._tag === 'Unsupported'
+                ? InstallState.Available()
+                : current,
+            ),
+          );
+        });
+        yield* listen(window, 'appinstalled', () => {
+          deferred = null;
+          Effect.runSync(SubscriptionRef.set(state, InstallState.Installed()));
+        });
+      }
+
+      const prompt = Effect.suspend(() => {
+        const event = deferred;
+        if (event === null) return Effect.succeed('unavailable' as const);
+        // The browser lets each event prompt once.
+        deferred = null;
+        return Effect.tryPromise(async () => {
+          await event.prompt();
+          return (await event.userChoice).outcome;
+        }).pipe(
+          Effect.tap((outcome) =>
+            outcome === 'accepted'
+              ? SubscriptionRef.set(state, InstallState.Installed())
+              : dismiss,
+          ),
+          Effect.orElseSucceed(() => 'unavailable' as const),
+        );
+      });
+
+      return { state, prompt, dismiss };
+    }),
+  );
+}
+
+const useInstallService = lazyService(Install, Install.layer);
+const UNSUPPORTED = InstallState.Unsupported();
+
+/**
+ * Install state with `prompt` and `dismiss`; `Unsupported` during SSR and
+ * until known. The browser offers install once, early, so call this (or
+ * render `InstallPrompt`) in the root component: that starts listening.
+ */
+export const useInstall = (): {
+  readonly state: InstallState;
+  readonly prompt: () => Promise<'accepted' | 'dismissed' | 'unavailable'>;
+  readonly dismiss: () => void;
+} => {
+  const install = useInstallService();
+  const state = useSubscriptionRef(install?.state, UNSUPPORTED);
+  return useMemo(
+    () => ({
+      state,
+      prompt: () =>
+        install === undefined
+          ? Promise.resolve('unavailable' as const)
+          : Effect.runPromise(install.prompt),
+      dismiss: () => {
+        if (install !== undefined) void Effect.runPromise(install.dismiss);
+      },
+    }),
+    [state, install],
+  );
+};

package/src/pwa/extras/install/ios.ts

@@ -0,0 +1,13 @@
+/** Safari on iPhone, iPod or iPad (iPadOS reports a Mac with touch). Other iOS browsers get no manual steps. */
+export const isIosSafari = (nav: {
+  readonly userAgent: string;
+  readonly maxTouchPoints: number;
+}): boolean => {
+  const ua = nav.userAgent;
+  const ios =
+    /iPad|iPhone|iPod/.test(ua) ||
+    (/Macintosh/.test(ua) && nav.maxTouchPoints > 1);
+  return (
+    ios && /Safari\//.test(ua) && !/CriOS|FxiOS|EdgiOS|OPiOS|GSA\//.test(ua)
+  );
+};

package/src/pwa/extras/install/media-query.ts

@@ -0,0 +1,18 @@
+import { useCallback, useSyncExternalStore } from 'react';
+
+/** `false` during SSR and hydration. */
+export const useMediaQuery = (query: string): boolean => {
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      const list = window.matchMedia(query);
+      list.addEventListener('change', onChange);
+      return () => list.removeEventListener('change', onChange);
+    },
+    [query],
+  );
+  return useSyncExternalStore(
+    subscribe,
+    () => window.matchMedia(query).matches,
+    () => false,
+  );
+};

package/src/pwa/extras/lazy-service/index.ts

@@ -0,0 +1 @@
+export { lazyService } from './lazy-service.js';

package/src/pwa/extras/lazy-service/lazy-service.ts

@@ -0,0 +1,38 @@
+import * as Context from 'effect/Context';
+import type * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import { useEffect, useState } from 'react';
+
+/**
+ * A hook for one page-wide service, built in the browser when the first
+ * component using it mounts and kept for the life of the page, so every
+ * caller shares it. `undefined` during SSR and until it is built.
+ */
+export const lazyService = <I, S>(
+  key: Context.Key<I, S>,
+  layer: Layer.Layer<I>,
+): (() => S | undefined) => {
+  let service: S | undefined;
+  let building: Promise<S> | undefined;
+  const build = () =>
+    (building ??= ManagedRuntime.make(layer)
+      .context()
+      .then((context) => (service = Context.get(context, key))));
+
+  return () => {
+    const [value, setValue] = useState(service);
+    useEffect(() => {
+      if (value !== undefined) return;
+      let mounted = true;
+      build().then(
+        (built) => mounted && setValue(built),
+        (error: unknown) =>
+          console.error('pwa-toolkit: extra failed to start', error),
+      );
+      return () => {
+        mounted = false;
+      };
+    }, [value]);
+    return value;
+  };
+};

package/src/pwa/extras/online/index.ts

@@ -0,0 +1,2 @@
+export { OfflineIndicator } from './offline-indicator.js';
+export { Online, useOnline } from './online.js';

package/src/pwa/extras/online/offline-indicator.tsx

@@ -0,0 +1,26 @@
+import { WifiOffIcon } from '#lib/lucide';
+import type { ReactNode } from 'react';
+import { useOnline } from './online.js';
+
+/**
+ * Shown while offline. The live region is always rendered so screen readers
+ * announce the change. It stacks above sheets and their backdrop (z-50).
+ */
+export const OfflineIndicator = (props: {
+  readonly message?: string;
+}): ReactNode => {
+  const online = useOnline();
+  return (
+    <div
+      role="status"
+      className="pointer-events-none fixed inset-x-0 top-[max(0.5rem,env(safe-area-inset-top))] z-60 flex justify-center"
+    >
+      {!online && (
+        <span className="inline-flex animate-in items-center gap-2 rounded-full bg-foreground px-3 py-1.5 text-xs font-medium text-background shadow-md duration-200 ease-out fade-in slide-in-from-top-1 motion-reduce:animate-none">
+          <WifiOffIcon aria-hidden="true" className="size-3.5" />
+          {props.message ?? "You're offline"}
+        </span>
+      )}
+    </div>
+  );
+};