@marktiderman/genesis-native 0.1.0 → 0.3.0

package/src/updates/screens.tsx

@@ -0,0 +1,159 @@
+/**
+ * The default renderers, built from `@marktiderman/genesis-ui-native`. Each
+ * is the default of one slot (`forceUpgrade`, `maintenance`, `updateBanner`,
+ * `whatsNew`) and is exported on its own.
+ */
+import { View } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
+import {
+  NativeBanner,
+  NativeButton,
+  NativeEmptyState,
+  NativeGlassSurface,
+  NativeSheet,
+  NativeSheetScrollView,
+  NativeText,
+  useLiquidGlass,
+} from "@marktiderman/genesis-ui-native/components";
+import type { ReleaseNote } from "./policy";
+
+export interface ForceUpgradeProps {
+  minimumVersion: string;
+  installedVersion: string;
+  /** The policy's store link for this platform (a minimum without one forces nothing). */
+  storeUrl: string;
+  /** Opens `storeUrl`. */
+  openStore: () => void;
+  /** Ask the policy again (it may have been lowered). */
+  retry: () => void;
+  checking: boolean;
+}
+
+/** Blocking: this version is below the minimum. "Update" opens the store. */
+export function ForceUpgradeScreen({ minimumVersion, installedVersion, openStore, retry, checking }: ForceUpgradeProps) {
+  return (
+    <View testID="genesis-force-upgrade" className="flex-1 justify-center bg-background">
+      <NativeEmptyState
+        variant="first-run"
+        title="Update required"
+        body={`This version (${installedVersion}) is no longer supported. Update to ${minimumVersion} or later to keep going.`}
+        primaryAction={
+          <NativeButton onPress={openStore} testID="genesis-force-upgrade-store">
+            Update
+          </NativeButton>
+        }
+        secondaryAction={
+          <NativeButton variant="ghost" onPress={retry} loading={checking} testID="genesis-force-upgrade-retry">
+            Check again
+          </NativeButton>
+        }
+        testID="genesis-force-upgrade-state"
+      />
+    </View>
+  );
+}
+
+export interface MaintenanceProps {
+  /** The policy's message, or `null` for the default copy. */
+  message: string | null;
+  retry: () => void;
+  retrying: boolean;
+}
+
+/** Blocking: the policy says maintenance is on. "Try again" asks again. */
+export function MaintenanceScreen({ message, retry, retrying }: MaintenanceProps) {
+  return (
+    <View testID="genesis-maintenance" className="flex-1 justify-center bg-background">
+      <NativeEmptyState
+        variant="first-run"
+        title="Down for maintenance"
+        body={message ?? "We're doing some work on the app. Try again in a few minutes."}
+        primaryAction={
+          <NativeButton onPress={retry} loading={retrying} testID="genesis-maintenance-retry">
+            Try again
+          </NativeButton>
+        }
+        testID="genesis-maintenance-state"
+      />
+    </View>
+  );
+}
+
+export interface UpdateBannerProps {
+  /** Reload into the downloaded update (refused while `canReload` is false). */
+  reload: () => void;
+  /** Hide the banner; the update still applies on the next cold start. */
+  dismiss: () => void;
+  /** False while something is mid-edit (`useBlockReload`) or your `canReload` says no. */
+  canReload: boolean;
+  /** The last tap was refused because something is mid-edit. */
+  blocked: boolean;
+  reloading: boolean;
+}
+
+/**
+ * Non-blocking: floats over the top of the screens while an update is
+ * downloaded. Liquid Glass on iOS 26 when the app passed expo-glass-effect
+ * (`modules.glass`); the solid secondary surface otherwise.
+ */
+export function UpdateBanner({ reload, dismiss, canReload, blocked, reloading }: UpdateBannerProps) {
+  // On glass the message drops its own fill, or it would cover the glass.
+  const onGlass = useLiquidGlass() !== null;
+  return (
+    <SafeAreaView edges={["top"]} pointerEvents="box-none" style={{ position: "absolute", top: 0, left: 0, right: 0 }}>
+      <View className="mx-3 mt-2">
+        <NativeGlassSurface testID="genesis-update-banner" fallbackClassName="overflow-hidden rounded-lg border border-border bg-secondary">
+          <NativeBanner
+            variant="info"
+            title="An update is ready"
+            description={blocked || !canReload ? "Finish what you're doing, then restart to use it." : "Restart to use the latest version."}
+            className={onGlass ? "border-b-0 border-transparent bg-transparent" : "border-b-0"}
+            testID="genesis-update-banner-message"
+          />
+          <View className="flex-row justify-end gap-2 px-4 pb-3">
+            <NativeButton variant="ghost" size="sm" onPress={dismiss} testID="genesis-update-banner-later">
+              Later
+            </NativeButton>
+            <NativeButton size="sm" onPress={reload} disabled={!canReload} loading={reloading} testID="genesis-update-banner-restart">
+              Restart
+            </NativeButton>
+          </View>
+        </NativeGlassSurface>
+      </View>
+    </SafeAreaView>
+  );
+}
+
+export interface WhatsNewProps {
+  /** Newest first. */
+  notes: readonly ReleaseNote[];
+  /** The installed version. */
+  version: string | null;
+  /** Close and remember this version. */
+  dismiss: () => void;
+}
+
+/** The release notes for this version, once, in a sheet. */
+export function WhatsNewSheet({ notes, dismiss }: WhatsNewProps) {
+  return (
+    <NativeSheet open onOpenChange={(open) => (open ? undefined : dismiss())} testID="genesis-whats-new">
+      {/* The notes scroll once they pass the sheet's height. */}
+      <NativeSheetScrollView contentContainerClassName="gap-4 p-6">
+        <NativeText preset="h3" accessibilityRole="header">
+          What's new
+        </NativeText>
+        {notes.map((note) => (
+          <View key={note.version} className="gap-1" testID={`genesis-whats-new-${note.version}`}>
+            <NativeText preset="label">{note.title ?? `Version ${note.version}`}</NativeText>
+            <NativeText preset="body-sm" className="text-muted-foreground">
+              {note.body}
+            </NativeText>
+          </View>
+        ))}
+        <NativeButton onPress={dismiss} testID="genesis-whats-new-done">
+          Got it
+        </NativeButton>
+      </NativeSheetScrollView>
+    </NativeSheet>
+  );
+}

package/src/updates/signature.ts

@@ -0,0 +1,80 @@
+/**
+ * The version signature: which binary and which update this is, in one
+ * line for Settings "About" and in a few lines for a support report.
+ *
+ *   1.4.0 (37) · preview · 3f2a9c1b
+ *   1.4.0 (37) · production · embedded
+ *   1.4.0 (37) · updates off
+ *
+ * A value the modules can't give is printed as `unknown`, never left out
+ * (an empty string counts as not given: expo-updates gives `""` for the
+ * runtime version in a development build); one that doesn't apply, with
+ * updates off, as `none`.
+ */
+import type { ApplicationLike, UpdatesModuleLike } from "./modules";
+
+export interface VersionSignature {
+  version: string | null;
+  build: string | null;
+  platform: string;
+  /** The build's channel (expo-updates). */
+  channel: string | null;
+  /** A channel picked on this device (a test build switched channels); `null` when it follows the build. */
+  requestedChannel: string | null;
+  runtimeVersion: string | null;
+  updateId: string | null;
+  /** `update`: a downloaded update runs. `embedded`: the binary's own code. `off`: updates are off (development, Expo Go). */
+  launch: "update" | "embedded" | "off";
+  /** expo-updates fell back to the embedded code after a failed launch. */
+  emergency: boolean;
+  /** One line, for an About row. */
+  short: string;
+  /** Several lines, for a support report. */
+  text: string;
+}
+
+export interface VersionSignatureInput {
+  application?: ApplicationLike;
+  updates?: UpdatesModuleLike;
+  /** `Platform.OS`. */
+  platform: string;
+  requestedChannel?: string | null;
+}
+
+const UNKNOWN = "unknown";
+
+/** A module's value, or null when it gave none (undefined, null or an empty string). */
+const given = (value: string | null | undefined): string | null => (typeof value === "string" && value.trim() !== "" ? value : null);
+
+export function versionSignature({ application, updates, platform, requestedChannel = null }: VersionSignatureInput): VersionSignature {
+  const version = given(application?.nativeApplicationVersion);
+  const build = given(application?.nativeBuildVersion);
+  const on = Boolean(updates?.isEnabled);
+  const channel = on ? given(updates?.channel) : null;
+  const updateId = on ? given(updates?.updateId) : null;
+  const runtimeVersion = given(updates?.runtimeVersion);
+  const launch: VersionSignature["launch"] = !on ? "off" : updates?.isEmbeddedLaunch ? "embedded" : "update";
+  const emergency = on && updates?.isEmergencyLaunch === true;
+  const shownChannel = requestedChannel ?? channel;
+
+  const head = `${version ?? UNKNOWN} (${build ?? UNKNOWN})`;
+  const parts = [head];
+  if (launch === "off") {
+    parts.push("updates off");
+  } else {
+    parts.push(shownChannel ?? "no channel");
+    parts.push(launch === "embedded" ? "embedded" : (updateId?.slice(0, 8) ?? UNKNOWN));
+  }
+  if (emergency) parts.push("emergency launch");
+  const short = parts.join(" · ");
+
+  const lines = [
+    `Version ${head}`,
+    `Platform ${platform}`,
+    `Channel ${channel ?? (on ? UNKNOWN : "none")}${requestedChannel && requestedChannel !== channel ? ` (switched to ${requestedChannel})` : ""}`,
+    `Runtime ${runtimeVersion ?? (on ? UNKNOWN : "none")}`,
+    `Update ${launch === "off" ? "updates off" : launch === "embedded" ? "embedded" : (updateId ?? UNKNOWN)}`,
+  ];
+  if (emergency) lines.push(`Emergency launch: ${updates?.emergencyLaunchReason ?? UNKNOWN}`);
+  return { version, build, platform, channel, requestedChannel, runtimeVersion, updateId, launch, emergency, short, text: lines.join("\n") };
+}

package/src/updates/store.ts

@@ -0,0 +1,33 @@
+/** A tiny external store for `useSyncExternalStore`: immutable state, one notify per change. */
+export interface Store<T> {
+  getState(): T;
+  setState(next: Partial<T>): void;
+  subscribe(listener: () => void): () => void;
+}
+
+export function createStore<T extends object>(initial: T): Store<T> {
+  let state = initial;
+  const listeners = new Set<() => void>();
+  return {
+    getState: () => state,
+    setState(next) {
+      const merged = { ...state, ...next };
+      if ((Object.keys(merged) as (keyof T)[]).every((key) => Object.is(merged[key], state[key]))) return;
+      state = merged;
+      for (const listener of [...listeners]) listener();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+/** Resolves after `ms`, or never when `ms` is not finite. */
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    if (Number.isFinite(ms)) setTimeout(resolve, Math.max(0, ms));
+  });
+}

package/src/updates/version.ts

@@ -0,0 +1,39 @@
+/**
+ * Version numbers: the store version an app reports (`1.4.0`, `1.10`) and
+ * the minimum a policy sets. Only plain dotted numbers count (one to four
+ * parts, as App Store Connect and Play accept). Anything else (`1.2-beta`,
+ * `latest`, an empty string, a number too large to compare exactly) does not
+ * parse, and a comparison with it has no answer (`null`), so a malformed
+ * minimum can never block anyone.
+ */
+
+const VERSION = /^\d+(?:\.\d+){0,3}$/;
+
+/** `"1.10"` → `[1, 10, 0, 0]`; `null` when it isn't a plain dotted version. */
+export function parseVersion(value: unknown): number[] | null {
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  if (!VERSION.test(text)) return null;
+  const parts = text.split(".").map(Number);
+  if (parts.some((part) => !Number.isSafeInteger(part))) return null;
+  while (parts.length < 4) parts.push(0);
+  return parts;
+}
+
+/** -1, 0 or 1 as `a` is older than, the same as or newer than `b`; `null` when either doesn't parse. */
+export function compareVersions(a: unknown, b: unknown): -1 | 0 | 1 | null {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) return null;
+  for (let i = 0; i < 4; i++) {
+    const l = left[i] ?? 0;
+    const r = right[i] ?? 0;
+    if (l !== r) return l < r ? -1 : 1;
+  }
+  return 0;
+}
+
+/** True only when both parse and `installed` is older than `minimum`. Fails open. */
+export function isBelowMinimum(installed: unknown, minimum: unknown): boolean {
+  return compareVersions(installed, minimum) === -1;
+}

package/src/updates/whats-new.ts

@@ -0,0 +1,122 @@
+/**
+ * What's new: release notes shown once per version, remembered in storage.
+ *
+ * - First launch after an install (nothing stored): nothing shows; the
+ *   version is remembered, so a new install never opens on a sheet.
+ * - A newer version than the one remembered: the notes for every version
+ *   after it, up to this one, newest first. Closing them remembers this
+ *   version. With no notes for it, the version is remembered once the policy
+ *   has answered from the network (or there is no policy source), so notes
+ *   that arrive late still show.
+ * - Storage that can't be read shows nothing (rather than every launch).
+ */
+import { createStore, type Store } from "./store";
+import { compareVersions } from "./version";
+import { toError, type UpdatesOnError, type UpdatesStorageLike } from "./modules";
+import type { ReleaseNote } from "./policy";
+
+export interface WhatsNewState {
+  status: "loading" | "hidden" | "showing";
+  notes: readonly ReleaseNote[];
+}
+
+export interface WhatsNewOptions {
+  storage?: UpdatesStorageLike;
+  /** The installed version notes are matched against. `null`: never shows. */
+  version: string | null;
+  /** Default `"genesis:updates:seen-version"`. */
+  storageKey?: string;
+  onError?: UpdatesOnError;
+}
+
+export interface WhatsNewStore extends Pick<Store<WhatsNewState>, "getState" | "subscribe"> {
+  /** Read the remembered version. Never rejects; runs once. */
+  load(): Promise<void>;
+  /** Recompute with the notes known now; `final` once no more notes can arrive. */
+  update(notes: readonly ReleaseNote[], final: boolean): void;
+  /** Close the notes and remember this version. */
+  dismiss(): void;
+}
+
+/** The notes after `seen`, up to `version`, newest first. */
+export function notesSince(notes: readonly ReleaseNote[], seen: string, version: string): ReleaseNote[] {
+  return notes
+    .filter((note) => {
+      if (note.version === version) return seen !== version;
+      const afterSeen = compareVersions(note.version, seen);
+      const upToNow = compareVersions(note.version, version);
+      return afterSeen === 1 && (upToNow === -1 || upToNow === 0);
+    })
+    .sort((a, b) => compareVersions(b.version, a.version) ?? 0);
+}
+
+export function createWhatsNewStore(options: WhatsNewOptions): WhatsNewStore {
+  const { storage, version, storageKey = "genesis:updates:seen-version", onError } = options;
+  const store = createStore<WhatsNewState>({ status: "loading", notes: [] });
+  // undefined: not read yet; null: nothing stored (a fresh install); false: unreadable.
+  let seen: string | null | false | undefined;
+  let loading: Promise<void> | null = null;
+  let pending: { notes: readonly ReleaseNote[]; final: boolean } | null = null;
+
+  const remember = () => {
+    if (!storage || !version) return;
+    seen = version;
+    Promise.resolve()
+      .then(() => storage.setItem(storageKey, version))
+      .catch((error) => {
+        try {
+          onError?.(toError(error), "storage");
+        } catch {
+          // ignore a failing reporter
+        }
+      });
+  };
+
+  const compute = (notes: readonly ReleaseNote[], final: boolean) => {
+    if (seen === undefined) {
+      pending = { notes, final };
+      return;
+    }
+    if (!version || seen === false) return store.setState({ status: "hidden", notes: [] });
+    if (seen === null) {
+      remember();
+      return store.setState({ status: "hidden", notes: [] });
+    }
+    const due = notesSince(notes, seen, version);
+    if (due.length > 0) return store.setState({ status: "showing", notes: due });
+    if (final && seen !== version) remember();
+    store.setState({ status: "hidden", notes: [] });
+  };
+
+  return {
+    getState: store.getState,
+    subscribe: store.subscribe,
+    load() {
+      loading ??= (async () => {
+        if (!storage || !version) {
+          seen = false;
+        } else {
+          try {
+            seen = await storage.getItem(storageKey);
+          } catch (error) {
+            seen = false;
+            try {
+              onError?.(toError(error), "storage");
+            } catch {
+              // ignore a failing reporter
+            }
+          }
+        }
+        const next = pending ?? { notes: [], final: false };
+        pending = null;
+        compute(next.notes, next.final);
+      })();
+      return loading;
+    },
+    update: compute,
+    dismiss() {
+      remember();
+      store.setState({ status: "hidden", notes: [] });
+    },
+  };
+}