@timmo001/groundwork-pwa 0.0.0-stage → 0.0.0

package/src/config.ts

@@ -0,0 +1,177 @@
+/**
+ * An app's `pwa.config`: what makes a Groundwork web app installable and
+ * usable as one on a phone, each piece on unless the config turns it off.
+ * Shared by the build, which writes the manifest, and the page.
+ */
+
+/** One of the manifest's icons. */
+export interface PwaIcon {
+  readonly src: string;
+  readonly sizes: string;
+  readonly type?: string;
+  readonly purpose?: "any" | "maskable" | "monochrome";
+}
+
+/** A shortcut in the launcher's long-press menu. */
+export interface PwaShortcut {
+  readonly name: string;
+  readonly url: string;
+  readonly shortName?: string;
+  readonly description?: string;
+  readonly icons?: readonly PwaIcon[];
+}
+
+/** Where shares arrive. */
+export interface ShareTargetConfig {
+  /** The page shares open, in the app's scope. Defaults to `startUrl`. */
+  readonly action?: string;
+}
+
+/** The service worker that keeps the app shell for offline starts. */
+export interface OfflineConfig {
+  /** The worker's script, in the app's scope. Defaults to `sw.js`. */
+  readonly worker?: string;
+  /** Pages and files cached when the worker installs. Defaults to `startUrl`. */
+  readonly shell?: readonly string[];
+}
+
+/** The modes a manifest's colors can come from. */
+export type PwaMode = "light" | "dark" | "darker";
+
+/** A value a manifest member can hold. */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+/** What a web app turns on. Only the name is needed. */
+export interface PwaConfig {
+  readonly name: string;
+  /** The name under the launcher icon. Defaults to `name`. */
+  readonly shortName?: string;
+  readonly description?: string;
+  /** The Groundwork theme the colors come from. Defaults to `base`. */
+  readonly theme?: string;
+  /**
+   * The mode the manifest's colors come from, for the splash screen and task
+   * switcher, which take one color. The page's own `theme-color` follows the
+   * system's mode. Defaults to `light`.
+   */
+  readonly mode?: PwaMode;
+  /** The browser's bar color. Defaults to the theme's `surface-default`. */
+  readonly themeColor?: string;
+  /** The splash screen's color. Defaults to the theme's `surface-default`. */
+  readonly backgroundColor?: string;
+  /** The app's identity across installs. Defaults to `startUrl`. */
+  readonly id?: string;
+  /** Defaults to `./`, the page the manifest sits beside. */
+  readonly startUrl?: string;
+  /** Defaults to `./`. */
+  readonly scope?: string;
+  /** Defaults to `standalone`. */
+  readonly display?: "standalone" | "minimal-ui" | "fullscreen" | "browser";
+  /** Defaults to `icons/icon-192.png`, `icon-512.png` and `maskable-512.png`. */
+  readonly icons?: readonly PwaIcon[];
+  readonly shortcuts?: readonly PwaShortcut[];
+  /** `<meta name="color-scheme" content="dark light">` and `theme-color` per mode. */
+  readonly colorScheme?: boolean;
+  /** Holds the browser's install prompt for the app to offer when it chooses. */
+  readonly install?: boolean;
+  /** Takes shares from other apps, delivered as a `gw-share` event. */
+  readonly shareTarget?: boolean | ShareTargetConfig;
+  /** A service worker that caches the app shell for offline starts. */
+  readonly offline?: boolean | OfflineConfig;
+  /**
+   * Manifest members to add or replace, written over the generated ones, such
+   * as `orientation`, `categories` or `screenshots`.
+   */
+  readonly manifest?: { readonly [key: string]: JsonValue };
+}
+
+/** Every option filled in. */
+export interface ResolvedPwaConfig {
+  readonly name: string;
+  readonly shortName: string;
+  readonly description: string;
+  readonly theme: string;
+  readonly mode: PwaMode;
+  readonly id: string;
+  readonly startUrl: string;
+  readonly scope: string;
+  readonly display: NonNullable<PwaConfig["display"]>;
+  readonly icons: readonly PwaIcon[];
+  readonly shortcuts: readonly PwaShortcut[];
+  readonly colorScheme: boolean;
+  readonly install: boolean;
+  readonly shareTarget: false | Required<ShareTargetConfig>;
+  readonly offline: false | Required<OfflineConfig>;
+  readonly themeColor: string | undefined;
+  readonly backgroundColor: string | undefined;
+  readonly manifest: { readonly [key: string]: JsonValue };
+}
+
+/** A share from another app, from the share target or the Android shell. */
+export interface Share {
+  readonly title?: string;
+  readonly text?: string;
+  readonly url?: string;
+}
+
+/** The query parameters the share target sends, kept apart from the app's own. */
+export const shareParams = {
+  title: "share-title",
+  text: "share-text",
+  url: "share-url",
+} as const satisfies Record<keyof Share, string>;
+
+/** Types a config in the app's `pwa.config.ts`. */
+export const definePwaConfig = (config: PwaConfig): PwaConfig => config;
+
+/** Fills in the defaults. */
+export const resolveConfig = (config: PwaConfig): ResolvedPwaConfig => {
+  const startUrl = config.startUrl ?? "./";
+  const share = config.shareTarget ?? true;
+  const offline = config.offline ?? true;
+
+  return {
+    name: config.name,
+    shortName: config.shortName ?? config.name,
+    description: config.description ?? "",
+    theme: config.theme ?? "base",
+    mode: config.mode ?? "light",
+    id: config.id ?? startUrl,
+    startUrl,
+    scope: config.scope ?? "./",
+    display: config.display ?? "standalone",
+    icons: config.icons ?? [
+      { src: "icons/icon-192.png", sizes: "192x192", type: "image/png" },
+      { src: "icons/icon-512.png", sizes: "512x512", type: "image/png" },
+      {
+        src: "icons/maskable-512.png",
+        sizes: "512x512",
+        type: "image/png",
+        purpose: "maskable",
+      },
+    ],
+    shortcuts: config.shortcuts ?? [],
+    colorScheme: config.colorScheme ?? true,
+    install: config.install ?? true,
+    shareTarget:
+      share === false
+        ? false
+        : { action: (share === true ? undefined : share.action) ?? startUrl },
+    offline:
+      offline === false
+        ? false
+        : {
+            worker: (offline === true ? undefined : offline.worker) ?? "sw.js",
+            shell: (offline === true ? undefined : offline.shell) ?? [startUrl],
+          },
+    themeColor: config.themeColor,
+    backgroundColor: config.backgroundColor,
+    manifest: config.manifest ?? {},
+  };
+};

package/src/pairing.ts

@@ -0,0 +1,142 @@
+/**
+ * The pairing contract: connecting a phone to a service without typing an
+ * address or a credential. The service shows a one-time link as text and a
+ * QR code; the app opens or scans it, trades the code for a token and keeps
+ * that. Documented on the Behavior page, beside push.
+ */
+import { Option, Schema } from "effect";
+
+import { PushClient } from "./push.ts";
+
+/** The service's route, under its own base URL. */
+export const pairingRoutes = {
+  /** `POST` a {@link PairingRequest}, answered with a {@link Pairing}. */
+  pair: "pair",
+} as const;
+
+/** The query parameter the link carries its one-time code in. */
+export const pairingParam = "pair";
+
+/**
+ * A pairing link: the service's base URL with the code, such as
+ * `https://bridge.local:9170/?pair=4f9c…`. It works once, and the service
+ * forgets it after `expires`, a few minutes after it was made.
+ */
+export const PairingLink = Schema.Struct({
+  service: Schema.String,
+  code: Schema.String,
+});
+
+export interface PairingLink extends Schema.Schema.Type<typeof PairingLink> {}
+
+/** What the app sends to trade the code: the code and who it is. */
+export const PairingRequest = Schema.Struct({
+  code: Schema.String,
+  client: PushClient,
+});
+
+export interface PairingRequest extends Schema.Schema.Type<
+  typeof PairingRequest
+> {}
+
+/**
+ * The service's answer: a token the app sends as `Authorization: Bearer`
+ * from then on, and the name to show for the service. The service keeps the
+ * client, when it paired and when it was last seen, and lists them so one
+ * can be removed, which ends its token.
+ */
+export const Pairing = Schema.Struct({
+  token: Schema.String,
+  service: Schema.Struct({ id: Schema.String, name: Schema.String }),
+});
+
+export interface Pairing extends Schema.Schema.Type<typeof Pairing> {}
+
+/** The link for a service and a code, for the text and the QR code. */
+export const pairingUrl = ({ service, code }: PairingLink): string => {
+  const url = new URL(service);
+
+  url.searchParams.set(pairingParam, code);
+
+  return url.href;
+};
+
+/** Reads a pairing link, or `undefined` when the text isn't one. */
+export const parsePairingLink = (text: string): PairingLink | undefined => {
+  if (!URL.canParse(text)) return undefined;
+
+  const url = new URL(text);
+  const code = url.searchParams.get(pairingParam);
+
+  if (code === null || code === "") return undefined;
+
+  url.searchParams.delete(pairingParam);
+
+  return { service: url.href, code };
+};
+
+const decodePairing = Schema.decodeUnknownOption(Pairing);
+
+/** Trades a link's code for a token, or `undefined` when the service refuses. */
+export const pair = async (
+  link: PairingLink,
+  client: PushClient,
+): Promise<Pairing | undefined> => {
+  const request: PairingRequest = { code: link.code, client };
+
+  const response = await fetch(new URL(pairingRoutes.pair, link.service), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(request),
+  });
+
+  if (!response.ok) return undefined;
+
+  return Option.getOrUndefined(decodePairing(await response.json()));
+};
+
+/** The parts of the Barcode Detection API scanning uses. */
+interface QrDetector {
+  readonly detect: (
+    source: HTMLVideoElement,
+  ) => Promise<readonly { readonly rawValue: string }[]>;
+}
+
+declare global {
+  var BarcodeDetector:
+    | (new (options: { readonly formats: readonly string[] }) => QrDetector)
+    | undefined;
+}
+
+/** True where the browser can read QR codes, as Chromium on Android can. */
+export const canScan = (): boolean => globalThis.BarcodeDetector !== undefined;
+
+/**
+ * Reads QR codes from a playing camera video until one is a pairing link,
+ * or the signal aborts. The page starts the camera, so it owns the
+ * permission prompt; the Android shell passes it through.
+ */
+export const scanPairingLink = async (
+  video: HTMLVideoElement,
+  signal: AbortSignal,
+): Promise<PairingLink | undefined> => {
+  const Detector = globalThis.BarcodeDetector;
+
+  if (Detector === undefined) return undefined;
+
+  const detector = new Detector({ formats: ["qr_code"] });
+
+  while (!signal.aborted) {
+    const codes = await detector.detect(video).catch(() => []);
+
+    const link = codes
+      .map(({ rawValue }) => parsePairingLink(rawValue))
+      .find((found) => found !== undefined);
+
+    if (link !== undefined) return link;
+
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+  }
+
+  return undefined;
+};

package/src/push.ts

@@ -0,0 +1,122 @@
+/**
+ * The push contract: how a service keeps its clients' push subscriptions and
+ * what it sends them. One shape for the PWA's Web Push, the Android shell's
+ * UnifiedPush and every service that pushes, documented on the Behavior page.
+ */
+import { Option, Schema } from "effect";
+
+/** The service's routes, under its own base URL. */
+export const pushRoutes = {
+  /** `GET`: the VAPID public key, as {@link VapidKey}. */
+  vapidKey: "push/vapid-key",
+  /** `POST` a {@link PushSubscription}; `DELETE` with `{ endpoint }` to stop. */
+  subscriptions: "push/subscriptions",
+} as const;
+
+/** The VAPID public key, base64url, for `pushManager.subscribe`. */
+export const VapidKey = Schema.Struct({ publicKey: Schema.String });
+
+export interface VapidKey extends Schema.Schema.Type<typeof VapidKey> {}
+
+/** The client a subscription belongs to, kept so one client has one. */
+export const PushClient = Schema.Struct({
+  /** Stable per install, such as a random id kept in storage. */
+  id: Schema.String,
+  /** What people see in the service's list of clients, such as "Pixel 9". */
+  name: Schema.String,
+  platform: Schema.Literals(["web", "android"]),
+});
+
+export interface PushClient extends Schema.Schema.Type<typeof PushClient> {}
+
+/**
+ * A subscription, as `PushSubscription.toJSON()` gives it in the browser and
+ * the shell sends a UnifiedPush endpoint. Posting one for a known client
+ * replaces that client's last.
+ */
+export const PushSubscription = Schema.Struct({
+  endpoint: Schema.String,
+  keys: Schema.Struct({ p256dh: Schema.String, auth: Schema.String }),
+  client: PushClient,
+});
+
+export interface PushSubscription extends Schema.Schema.Type<
+  typeof PushSubscription
+> {}
+
+/** Ongoing work, shown as a Live Update on Android 16 and a plain one below. */
+export const PushOngoing = Schema.Struct({
+  /** Replaces the last update with the same id, and ends it when `done`. */
+  id: Schema.String,
+  status: Schema.String,
+  progress: Schema.optionalKey(
+    Schema.Struct({ value: Schema.Number, max: Schema.Number }),
+  ),
+  done: Schema.optionalKey(Schema.Boolean),
+});
+
+export interface PushOngoing extends Schema.Schema.Type<typeof PushOngoing> {}
+
+/**
+ * What a push carries. The notification points at a page: `link` opens it,
+ * relative to the app's scope. `data` is the app's own, passed through.
+ */
+export const PushPayload = Schema.Struct({
+  title: Schema.String,
+  body: Schema.optionalKey(Schema.String),
+  tone: Schema.optionalKey(
+    Schema.Literals([
+      "neutral",
+      "accent",
+      "info",
+      "success",
+      "warning",
+      "danger",
+      "important",
+    ]),
+  ),
+  link: Schema.optionalKey(Schema.String),
+  /** Like notifications share a tag, so a new one replaces the last. */
+  tag: Schema.optionalKey(Schema.String),
+  /** An alert shows on screen; a passive one only goes to the shade. */
+  level: Schema.optionalKey(Schema.Literals(["alert", "passive"])),
+  ongoing: Schema.optionalKey(PushOngoing),
+  data: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+});
+
+export interface PushPayload extends Schema.Schema.Type<typeof PushPayload> {}
+
+const decodePayloadJson = Schema.decodeUnknownOption(
+  Schema.fromJsonString(PushPayload),
+);
+
+/** Reads a push's text, or `undefined` when it isn't a payload. */
+export const decodePushPayload = (text: string): PushPayload | undefined =>
+  Option.getOrUndefined(decodePayloadJson(text));
+
+/** What `DELETE push/subscriptions` takes. */
+export const PushUnsubscribe = Schema.Struct({ endpoint: Schema.String });
+
+export interface PushUnsubscribe extends Schema.Schema.Type<
+  typeof PushUnsubscribe
+> {}
+
+const decodeSubscriptionJson = Schema.decodeUnknownOption(
+  Schema.fromJsonString(PushSubscription),
+);
+
+const decodeUnsubscribeJson = Schema.decodeUnknownOption(
+  Schema.fromJsonString(PushUnsubscribe),
+);
+
+/** For a service: reads a posted subscription, or `undefined`. */
+export const decodePushSubscription = (
+  text: string,
+): PushSubscription | undefined =>
+  Option.getOrUndefined(decodeSubscriptionJson(text));
+
+/** For a service: reads a `DELETE` body, or `undefined`. */
+export const decodePushUnsubscribe = (
+  text: string,
+): PushUnsubscribe | undefined =>
+  Option.getOrUndefined(decodeUnsubscribeJson(text));

package/src/view.ts

@@ -0,0 +1,258 @@
+/**
+ * The page half of `@timmo001/groundwork-pwa`: registers the service worker,
+ * holds the browser's install prompt for the app to offer, and hands shares
+ * from the share target to the app as a `gw-share` event, the same event the
+ * Android shell sends for a received share.
+ *
+ *   import config from "../pwa.config.ts";
+ *
+ *   const pwa = connectPwa(config, { onShare: (share) => openDraft(share) });
+ *
+ *   if (pwa.canInstall()) showInstallButton(() => pwa.install());
+ */
+import { Option, Schema } from "effect";
+
+import {
+  resolveConfig,
+  shareParams,
+  type PwaConfig,
+  type ResolvedPwaConfig,
+  type Share,
+} from "./config.ts";
+import {
+  pushRoutes,
+  VapidKey,
+  type PushClient,
+  type PushSubscription as ContractSubscription,
+} from "./push.ts";
+
+export * from "./config.ts";
+
+/** Where the app subscribes to a service's pushes. */
+export interface PushServiceOptions {
+  /** The service's base URL, which serves the push contract's routes. */
+  readonly service: string;
+  /** This install, the same client the pairing sent. */
+  readonly client: PushClient;
+  /** Sent with each request, such as the pairing's `Authorization`. */
+  readonly headers?: Record<string, string>;
+}
+
+/** Where push stands: off in this browser, not asked, refused, or on. */
+export type PushState = "unsupported" | "default" | "denied" | "subscribed";
+
+const decodeVapidKey = Schema.decodeUnknownOption(VapidKey);
+
+/** Whether this browser can push and whether the app is subscribed. */
+export const pushState = async (
+  registration: ServiceWorkerRegistration | undefined,
+): Promise<PushState> => {
+  if (registration === undefined || !("PushManager" in window))
+    return "unsupported";
+
+  if (Notification.permission === "denied") return "denied";
+
+  const existing = await registration.pushManager.getSubscription();
+
+  return existing === null ? "default" : "subscribed";
+};
+
+/**
+ * Asks for notifications, subscribes with the service's VAPID key and posts
+ * the subscription. Only a tap or click may ask, so call it from one, as the
+ * install offer is. Returns the state it ends in.
+ */
+export const subscribePush = async (
+  registration: ServiceWorkerRegistration | undefined,
+  { service, client, headers = {} }: PushServiceOptions,
+): Promise<PushState> => {
+  if (registration === undefined || !("PushManager" in window))
+    return "unsupported";
+
+  const permission = await Notification.requestPermission();
+
+  // Dismissing the prompt leaves it at "default", to ask again later
+  if (permission !== "granted")
+    return permission === "denied" ? "denied" : "default";
+
+  const key = await fetch(new URL(pushRoutes.vapidKey, service), { headers })
+    .then((response) => response.json())
+    .then((body) => Option.getOrUndefined(decodeVapidKey(body)));
+
+  if (key === undefined) return "default";
+
+  // One made with another key, such as the service's last, can't be reused
+  await (await registration.pushManager.getSubscription())?.unsubscribe();
+
+  const subscription = await registration.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: key.publicKey,
+  });
+
+  const { endpoint, keys } = subscription.toJSON();
+  const p256dh = keys?.["p256dh"];
+  const auth = keys?.["auth"];
+
+  if (endpoint === undefined || p256dh === undefined || auth === undefined)
+    return "default";
+
+  const body: ContractSubscription = {
+    endpoint,
+    keys: { p256dh, auth },
+    client,
+  };
+
+  const response = await fetch(new URL(pushRoutes.subscriptions, service), {
+    method: "POST",
+    headers: { ...headers, "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  return response.ok ? "subscribed" : "default";
+};
+
+/** Stops the app's pushes, here and at the service. */
+export const unsubscribePush = async (
+  registration: ServiceWorkerRegistration | undefined,
+  { service, headers = {} }: PushServiceOptions,
+): Promise<void> => {
+  const subscription = await registration?.pushManager.getSubscription();
+
+  if (subscription === null || subscription === undefined) return;
+
+  await fetch(new URL(pushRoutes.subscriptions, service), {
+    method: "DELETE",
+    headers: { ...headers, "content-type": "application/json" },
+    body: JSON.stringify({ endpoint: subscription.endpoint }),
+  });
+  await subscription.unsubscribe();
+};
+
+/** Chromium's `beforeinstallprompt` event, which other engines don't send. */
+interface InstallPromptEvent extends Event {
+  readonly prompt: () => Promise<void>;
+  readonly userChoice: Promise<{ readonly outcome: "accepted" | "dismissed" }>;
+}
+
+const isInstallPrompt = (event: Event): event is InstallPromptEvent =>
+  "prompt" in event && "userChoice" in event;
+
+/** What `connectPwa` sets up. */
+export interface ConnectPwaOptions {
+  /** Called with each share, from the share target or the Android shell. */
+  readonly onShare?: (share: Share) => void;
+  /** Called when the app can offer to install itself, and again when it can't. */
+  readonly onInstallChange?: (canInstall: boolean) => void;
+}
+
+/** The answer to an install offer. */
+export type InstallOutcome = "accepted" | "dismissed" | "unavailable";
+
+/** The page's PWA connection. */
+export interface Pwa {
+  readonly config: ResolvedPwaConfig;
+  /** True when the app runs installed, in its own window. */
+  readonly installed: () => boolean;
+  /** True while the browser has an install prompt to show. */
+  readonly canInstall: () => boolean;
+  /** Shows the browser's install prompt, which only a tap or click may do. */
+  readonly install: () => Promise<InstallOutcome>;
+  /** The service worker's registration, once it's registered. */
+  readonly worker: Promise<ServiceWorkerRegistration | undefined>;
+}
+
+/** Reads a share from the page's address and takes its parameters off it. */
+const takeShare = (): Share | undefined => {
+  const url = new URL(location.href);
+
+  const share = Object.fromEntries(
+    Object.entries(shareParams).flatMap(([key, param]) => {
+      const value = url.searchParams.get(param);
+
+      url.searchParams.delete(param);
+
+      return value === null || value === "" ? [] : [[key, value]];
+    }),
+  ) satisfies Share;
+
+  if (Object.keys(share).length === 0) return undefined;
+
+  // A reload shouldn't deliver the same share twice
+  history.replaceState(history.state, "", url);
+
+  return share;
+};
+
+/** Sets up what the config leaves on. */
+export const connectPwa = (
+  config: PwaConfig,
+  options: ConnectPwaOptions = {},
+): Pwa => {
+  const pwa = resolveConfig(config);
+  let prompt: InstallPromptEvent | undefined;
+
+  const installed = () =>
+    matchMedia("(display-mode: standalone)").matches ||
+    matchMedia("(display-mode: fullscreen)").matches;
+
+  const setPrompt = (event: InstallPromptEvent | undefined) => {
+    prompt = event;
+    options.onInstallChange?.(event !== undefined);
+    window.dispatchEvent(
+      new CustomEvent("gw-install-change", {
+        detail: { canInstall: event !== undefined },
+      }),
+    );
+  };
+
+  if (pwa.install) {
+    window.addEventListener("beforeinstallprompt", (event) => {
+      if (!isInstallPrompt(event)) return;
+      // Kept for the app's own button, rather than the browser's banner
+      event.preventDefault();
+      setPrompt(event);
+    });
+    window.addEventListener("appinstalled", () => setPrompt(undefined));
+  }
+
+  window.addEventListener("gw-share", (event) => {
+    if (event instanceof CustomEvent) options.onShare?.(event.detail);
+  });
+
+  if (pwa.shareTarget !== false) {
+    const share = takeShare();
+
+    // After the app's own listeners, which it adds once this returns
+    if (share !== undefined)
+      queueMicrotask(() =>
+        window.dispatchEvent(new CustomEvent("gw-share", { detail: share })),
+      );
+  }
+
+  const worker =
+    pwa.offline !== false && "serviceWorker" in navigator
+      ? navigator.serviceWorker
+          .register(pwa.offline.worker, { scope: pwa.scope })
+          .catch((error: Error) => {
+            console.warn("The service worker didn't register", error);
+
+            return undefined;
+          })
+      : Promise.resolve(undefined);
+
+  return {
+    config: pwa,
+    installed,
+    canInstall: () => prompt !== undefined,
+    install: async () => {
+      if (prompt === undefined) return "unavailable";
+      const event = prompt;
+
+      setPrompt(undefined);
+      await event.prompt();
+
+      return (await event.userChoice).outcome;
+    },
+    worker,
+  };
+};