@marktiderman/genesis-native 0.1.0 → 0.3.0

package/src/push/registration.ts

@@ -0,0 +1,189 @@
+/**
+ * This device's Expo push token, kept against whoever is signed in.
+ *
+ *   sync(userId)   permission granted → (Android) channels → token → backend.register,
+ *                  again when the token changes and at most hourly otherwise (last seen)
+ *   forget()       backend.forget(token) on sign-out, an account switch or deletion;
+ *                  a forget that fails offline is kept and retried at the next start
+ *
+ * The token is remembered on the phone (storage) with the user it was
+ * registered for, so it can be forgotten after the session has ended. Every
+ * step runs in order on one queue, so a sign-out never races a registration.
+ */
+import { createStore, type Store } from "../updates/store";
+import type { PushBackend } from "./backend";
+import { report, type NotificationsModuleLike, type PushOnError, type PushStorageLike } from "./modules";
+
+export type RegistrationStatus = "idle" | "registering" | "registered" | "unavailable" | "error";
+
+export interface RegistrationState {
+  status: RegistrationStatus;
+  /**
+   * Why it isn't registered: `no_project_id` (the build has no EAS project id, so there is no
+   * Expo push token), `no_token` (the OS gave none: a simulator without push, or no network),
+   * `backend` (the server refused or couldn't be reached).
+   */
+  problem: "no_project_id" | "no_token" | "backend" | null;
+}
+
+export interface Registration extends Store<RegistrationState> {
+  sync(userId: string, options?: { force?: boolean }): Promise<void>;
+  forget(): Promise<void>;
+  /** Retry forgets that failed earlier (offline sign-out). */
+  flush(): Promise<void>;
+  /** This device's token, once known (the person's own; never shown in logs). */
+  token(): string | null;
+}
+
+interface Saved {
+  token: string;
+  userId: string;
+  at: number;
+}
+
+/** Registered again at most this often while nothing changed (last seen, and a token another login took comes back). */
+const REFRESH_MS = 60 * 60_000;
+
+export function createRegistration(options: {
+  notifications?: NotificationsModuleLike;
+  backend: PushBackend;
+  projectId?: string | null;
+  platform: string;
+  appVersion?: string | null;
+  storage?: PushStorageLike;
+  storageKeyPrefix: string;
+  /** Creates the Android channels; runs before the token is asked for. */
+  ensureChannels: () => Promise<void>;
+  /** Is this user still the one signed in? A sync for someone who has signed out is dropped. */
+  isCurrent: (userId: string) => boolean;
+  now: () => number;
+  onError?: PushOnError;
+}): Registration {
+  const { notifications, backend, storage, storageKeyPrefix, onError, now } = options;
+  const savedKey = `${storageKeyPrefix}:device`;
+  const pendingKey = `${storageKeyPrefix}:forget`;
+  const store = createStore<RegistrationState>({ status: "idle", problem: null });
+  let current: string | null = null;
+  let queue: Promise<unknown> = Promise.resolve();
+  let warnedNoProject = false;
+
+  const run = <T>(step: () => Promise<T>): Promise<T> => {
+    const next = queue.then(step, step);
+    queue = next.catch(() => {});
+    return next;
+  };
+
+  const read = async <T>(key: string, fallback: T): Promise<T> => {
+    if (!storage) return fallback;
+    try {
+      const raw = await storage.getItem(key);
+      return raw ? (JSON.parse(raw) as T) : fallback;
+    } catch (error) {
+      report(onError, error, "storage");
+      return fallback;
+    }
+  };
+  const write = async (key: string, value: unknown) => {
+    try {
+      if (value === null) await storage?.removeItem?.(key);
+      else await storage?.setItem(key, JSON.stringify(value));
+    } catch (error) {
+      report(onError, error, "storage");
+    }
+  };
+
+  const forgetToken = async (token: string): Promise<boolean> => {
+    try {
+      await backend.forget(token);
+      return true;
+    } catch (error) {
+      report(onError, error, "forget");
+      return false;
+    }
+  };
+
+  const queuePending = async (token: string) => {
+    const pending = await read<string[]>(pendingKey, []);
+    if (!pending.includes(token)) await write(pendingKey, [...pending, token].slice(-10));
+  };
+
+  return {
+    ...store,
+    token: () => current,
+    sync(userId, { force = false } = {}) {
+      return run(async () => {
+        if (!notifications || !options.isCurrent(userId)) return;
+        if (!options.projectId) {
+          store.setState({ status: "unavailable", problem: "no_project_id" });
+          if (!warnedNoProject) {
+            warnedNoProject = true;
+            // Loud once: without an EAS project id there is no Expo push token, so no push reaches this build.
+            report(onError, new Error("push: no EAS project id (projectId), so this build gets no push token. Run `eas init` and pass Constants.expoConfig.extra.eas.projectId."), "setup");
+          }
+          return;
+        }
+        store.setState({ status: "registering", problem: null });
+        await options.ensureChannels().catch((error) => report(onError, error, "channels"));
+        let token: string;
+        try {
+          token = (await notifications.getExpoPushTokenAsync({ projectId: options.projectId })).data;
+        } catch (error) {
+          report(onError, error, "register");
+          store.setState({ status: "error", problem: "no_token" });
+          return;
+        }
+        if (typeof token !== "string" || token.length === 0) {
+          store.setState({ status: "error", problem: "no_token" });
+          return;
+        }
+        current = token;
+        const saved = await read<Saved | null>(savedKey, null);
+        // A different token kept for someone else on this phone: forget it. (The same token the server moves itself.)
+        if (saved && saved.userId !== userId && saved.token !== token && !(await forgetToken(saved.token))) await queuePending(saved.token);
+        if (!force && saved && saved.token === token && saved.userId === userId && now() - saved.at < REFRESH_MS) {
+          store.setState({ status: "registered", problem: null });
+          return;
+        }
+        if (!options.isCurrent(userId)) return;
+        try {
+          await backend.register(token, options.platform === "ios" ? "ios" : "android", options.appVersion ?? null);
+        } catch (error) {
+          report(onError, error, "register");
+          store.setState({ status: "error", problem: "backend" });
+          return;
+        }
+        // An older token this phone had (the OS rotated it) goes; the new one stays.
+        if (saved && saved.token !== token && saved.userId === userId && !(await forgetToken(saved.token))) await queuePending(saved.token);
+        await write(savedKey, { token, userId, at: now() } satisfies Saved);
+        // A forget of this same token still waiting from an offline sign-out would undo this registration.
+        const pending = await read<string[]>(pendingKey, []);
+        if (pending.includes(token)) await write(pendingKey, pending.filter((t) => t !== token).length ? pending.filter((t) => t !== token) : null);
+        store.setState({ status: "registered", problem: null });
+      });
+    },
+    forget() {
+      return run(async () => {
+        const saved = await read<Saved | null>(savedKey, null);
+        const token = saved?.token ?? current;
+        await write(savedKey, null);
+        store.setState({ status: "idle", problem: null });
+        if (!token) return;
+        if (!(await forgetToken(token))) await queuePending(token);
+      });
+    },
+    flush() {
+      return run(async () => {
+        const pending = await read<string[]>(pendingKey, []);
+        if (pending.length === 0) return;
+        const left: string[] = [];
+        const registered = (await read<Saved | null>(savedKey, null))?.token;
+        for (const token of pending) {
+          // Registered again since (signed back in): keep it.
+          if (token === registered) continue;
+          if (!(await forgetToken(token))) left.push(token);
+        }
+        await write(pendingKey, left.length ? left : null);
+      });
+    },
+  };
+}

package/src/push/routing.ts

@@ -0,0 +1,27 @@
+/**
+ * Where a tapped notification goes. The sender puts an app path in
+ * `data.url` (`/messages/42`); it goes through the same `normalizeLink` as
+ * every deep link, so a path the app doesn't know opens `/` and an ignored
+ * one goes nowhere. Without link options, only a plain app path is followed.
+ */
+import { normalizeLink, type LinkOptions } from "../links";
+import type { NotificationLike, NotificationResponseLike } from "./modules";
+
+const ANY_PATH: LinkOptions = { map: { "/*": "/*" } };
+
+/** The data a notification carries (`content.data`), or `{}`. */
+export function notificationData(notification: NotificationLike): Record<string, unknown> {
+  const data = notification.request?.content?.data;
+  return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+}
+
+/** The app path a tap should open, or null. */
+export function pathForResponse(response: NotificationResponseLike, links?: LinkOptions): string | null {
+  const url = notificationData(response.notification).url;
+  if (typeof url !== "string" || url.length === 0 || url.length > 2048) return null;
+  if (links) return normalizeLink(url, links);
+  // No link map: an app path only (never another app's URL), with "." and ".." refused as normalizeLink does.
+  if (!url.startsWith("/") || url.startsWith("//") || url.includes("\\")) return null;
+  const path = normalizeLink(url, ANY_PATH);
+  return path === "/" && url.split(/[?#]/)[0] !== "/" ? null : path;
+}

package/src/push/screens.tsx

@@ -0,0 +1,46 @@
+/**
+ * The soft pre-prompt: the default of the `pushPrompt` slot, built from
+ * `@marktiderman/genesis-ui-native`. It says what push is for before the
+ * system asks, so a person who isn't ready says "Not now" here, where the
+ * app can ask again later, rather than "Don't Allow" there, where it can't.
+ */
+import { View } from "react-native";
+import { NativeButton, NativeSheet, NativeText } from "@marktiderman/genesis-ui-native/components";
+
+export interface PushPromptProps {
+  /** What `offer(reason)` said push is for here ("to hear when someone replies"), or null. */
+  reason: string | null;
+  /** "Turn on": shows the system prompt. */
+  accept: () => void;
+  /** "Not now": asks again after the cooldown, never more than `maxDeclines` times. */
+  decline: () => void;
+  title?: string;
+  body?: string;
+  acceptLabel?: string;
+  declineLabel?: string;
+}
+
+// The sheet is iOS's full-height page sheet: grow to fill it and centre the few lines in it, rather
+// than leave them at the top of an empty sheet. On Android the panel sizes to its content.
+const PROMPT_CONTENT = { flexGrow: 1, justifyContent: "center", gap: 16, padding: 24 } as const;
+
+export function PushPromptSheet({ reason, accept, decline, title, body, acceptLabel, declineLabel }: PushPromptProps) {
+  return (
+    <NativeSheet open onOpenChange={(open) => (open ? undefined : decline())} testID="genesis-push-prompt">
+      <View style={PROMPT_CONTENT} testID="genesis-push-prompt-content">
+        <NativeText preset="h3" accessibilityRole="header">
+          {title ?? "Turn on notifications?"}
+        </NativeText>
+        <NativeText preset="body" className="text-muted-foreground" testID="genesis-push-prompt-body">
+          {body ?? (reason ? `Get a notification ${reason}. You can change this any time in Settings.` : "Get a notification when something needs you. You can change this any time in Settings.")}
+        </NativeText>
+        <NativeButton onPress={accept} testID="genesis-push-prompt-accept">
+          {acceptLabel ?? "Turn on"}
+        </NativeButton>
+        <NativeButton variant="ghost" onPress={decline} testID="genesis-push-prompt-decline">
+          {declineLabel ?? "Not now"}
+        </NativeButton>
+      </View>
+    </NativeSheet>
+  );
+}

package/src/push/settings.tsx

@@ -0,0 +1,378 @@
+/**
+ * `<NotificationSettings>`: the notification preferences screen, a Genesis
+ * `SettingsPage` with four parts:
+ *
+ *   permission   whether this phone may show notifications; Turn on / Open Settings
+ *   categories   a switch per category the app defined
+ *   quietHours   a switch, from and to times, and the time zone they're read in
+ *   privacy      show previews (off: the sender sends neutral text instead)
+ *
+ * Each part is a slot (`slots.quietHours = MyQuietHours` replaces it inside
+ * the same section, `null` drops the section) and a hook
+ * (`useQuietHours()` …) for a screen of your own. Saving is immediate; a save
+ * that fails is put back and said.
+ */
+import { useEffect, useMemo, useSyncExternalStore, type ComponentType, type ReactNode } from "react";
+import type { SlotPropsFor, Slots } from "@marktiderman/genesis-core/slots";
+import { NativeSwitch, NativeTimePicker } from "@marktiderman/genesis-ui-native/components";
+import { SettingsPage, type SettingsPageProps, type SettingsPageRow, type SettingsPageSection } from "@marktiderman/genesis-ui-native/layouts";
+import { useSession } from "../auth";
+import { PUSH_STATUS_LABELS, usePush, useNotificationPreferences, usePushPermissionState, usePushRegistration } from "./block";
+import type { PushPermissionStatus } from "./permission";
+import { clockOf, dateAt, deviceTimeZone, isQuietAt } from "./quiet-hours";
+
+export interface NotificationSettingsCopy {
+  permissionSection: string;
+  allow: string;
+  status: Record<PushPermissionStatus, string>;
+  turnOn: string;
+  openSettings: string;
+  noProjectId: string;
+  noToken: string;
+  registerFailed: string;
+  categoriesSection: string;
+  categoriesFootnote: string;
+  quietHoursSection: string;
+  quietHours: string;
+  quietHoursOnNow: string;
+  from: string;
+  to: string;
+  timeZone: string;
+  useDeviceTimeZone: string;
+  noTimeZone: string;
+  quietHoursFootnote: string;
+  privacySection: string;
+  showPreviews: string;
+  previewsFootnote: string;
+  saveFailed: string;
+  loadFailed: string;
+}
+
+export const notificationSettingsCopy: NotificationSettingsCopy = {
+  permissionSection: "Notifications",
+  allow: "Allow notifications",
+  status: PUSH_STATUS_LABELS,
+  turnOn: "Turn on",
+  openSettings: "Open Settings",
+  noProjectId: "This build can't get notifications: it has no EAS project id.",
+  noToken: "This phone didn't give the app a push token. Try again on a device with a network connection.",
+  registerFailed: "Couldn't turn notifications on for this phone. They'll be tried again next time you open the app.",
+  categoriesSection: "Notify me about",
+  categoriesFootnote: "Applies to every phone you're signed in on.",
+  quietHoursSection: "Quiet hours",
+  quietHours: "Quiet hours",
+  quietHoursOnNow: "On now",
+  from: "From",
+  to: "To",
+  timeZone: "Time zone",
+  useDeviceTimeZone: "Tap to use this phone's",
+  noTimeZone: "This phone didn't say its time zone, so quiet hours can't be placed in your day.",
+  quietHoursFootnote: "Notifications that arrive during quiet hours wait until they end. Urgent ones still come through.",
+  privacySection: "Privacy",
+  showPreviews: "Show previews",
+  previewsFootnote: "When off, notifications say only that there's something new; what they say stays on the server, off your lock screen.",
+  saveFailed: "Couldn't save that change. Check your connection and try again.",
+  loadFailed: "Couldn't load your notification settings, so they can't be changed yet. Check your connection; they load again when you come back here.",
+};
+
+/** The permission part's props: what `usePushPermission()` returns. */
+export interface PermissionPartProps {
+  status: PushPermissionStatus;
+  requesting: boolean;
+  /** Shows the system prompt (a tap is the person's intent, so no soft prompt first). */
+  request: () => void;
+  /** Opens the app's page in Settings, once the system won't ask again. */
+  openSettings: (() => void) | null;
+  /** Why this phone isn't registered, in the copy's words, or null. */
+  problem: string | null;
+  copy: NotificationSettingsCopy;
+}
+
+export interface CategoryRow {
+  id: string;
+  title: string;
+  description?: string;
+  on: boolean;
+}
+
+export interface CategoriesPartProps {
+  /** The saved settings aren't loaded (yet): nothing can change, so nothing overwrites them. */
+  disabled: boolean;
+  categories: CategoryRow[];
+  setOn: (id: string, on: boolean) => void;
+  saving: boolean;
+  copy: NotificationSettingsCopy;
+}
+
+export interface QuietHoursPartProps {
+  /** The saved settings aren't loaded (yet): nothing can change, so nothing overwrites them. */
+  disabled: boolean;
+  enabled: boolean;
+  start: string;
+  end: string;
+  timeZone: string | null;
+  /** This phone's zone, when it differs from the saved one (it travelled). */
+  deviceTimeZone: string | null;
+  /** In quiet hours right now (shown only; the server decides). */
+  activeNow: boolean;
+  setEnabled: (on: boolean) => void;
+  setStart: (clock: string) => void;
+  setEnd: (clock: string) => void;
+  adoptDeviceTimeZone: () => void;
+  saving: boolean;
+  copy: NotificationSettingsCopy;
+}
+
+export interface PrivacyPartProps {
+  /** The saved settings aren't loaded (yet): nothing can change, so nothing overwrites them. */
+  disabled: boolean;
+  hidePreviews: boolean;
+  setHidePreviews: (hide: boolean) => void;
+  saving: boolean;
+  copy: NotificationSettingsCopy;
+}
+
+// A type, not an interface, so it fits the slots contract's Record constraint.
+export type NotificationSettingsSlots = {
+  permission: PermissionPartProps;
+  categories: CategoriesPartProps;
+  quietHours: QuietHoursPartProps;
+  privacy: PrivacyPartProps;
+};
+
+const DEFAULT_COPY = notificationSettingsCopy;
+
+/** The permission part (rung 4). */
+export function usePushPermission(copy: NotificationSettingsCopy = DEFAULT_COPY): PermissionPartProps {
+  const block = usePush();
+  const { status, requesting } = usePushPermissionState();
+  const { problem } = usePushRegistration();
+  const open = block.options.openSettings;
+  return {
+    status,
+    requesting,
+    request: () => void block.permission.request(),
+    openSettings: open
+      ? () => {
+          Promise.resolve()
+            .then(open)
+            .catch((error: unknown) => block.options.onError?.(error instanceof Error ? error : new Error("openSettings failed"), "permission"));
+        }
+      : null,
+    problem: problem === "no_project_id" ? copy.noProjectId : problem === "no_token" ? copy.noToken : problem === "backend" ? copy.registerFailed : null,
+    copy,
+  };
+}
+
+/** The categories part (rung 4). */
+export function useNotificationCategories(copy: NotificationSettingsCopy = DEFAULT_COPY): CategoriesPartProps {
+  const block = usePush();
+  const { preferences, saving, update, status } = useNotificationPreferences();
+  const categories = useMemo(
+    () =>
+      block.categories.map((c) => ({
+        id: c.id,
+        title: c.title,
+        description: c.description,
+        on: typeof preferences.categories[c.id] === "boolean" ? preferences.categories[c.id]! : (c.defaultOn ?? true),
+      })),
+    [block.categories, preferences.categories],
+  );
+  return {
+    categories,
+    setOn: (id, on) => void update((p) => ({ ...p, categories: { ...p.categories, [id]: on } })),
+    saving,
+    disabled: status !== "ready",
+    copy,
+  };
+}
+
+/** The quiet-hours part (rung 4). */
+export function useQuietHours(copy: NotificationSettingsCopy = DEFAULT_COPY): QuietHoursPartProps {
+  const { preferences, saving, update, status } = useNotificationPreferences();
+  const q = preferences.quietHours;
+  const device = deviceTimeZone();
+  // Re-read each minute only while shown; the server is what decides.
+  const minute = useMinute();
+  const setQuiet = (change: Partial<typeof q>) => void update((p) => ({ ...p, quietHours: { ...p.quietHours, ...change } }));
+  return {
+    enabled: q.enabled,
+    start: q.start,
+    end: q.end,
+    timeZone: q.timeZone,
+    deviceTimeZone: device && device !== q.timeZone ? device : null,
+    activeNow: isQuietAt(q, new Date(minute)),
+    // Turning quiet hours on fills in this phone's zone if none was saved.
+    setEnabled: (on) => setQuiet(on ? { enabled: true, timeZone: q.timeZone ?? device } : { enabled: false }),
+    setStart: (start) => setQuiet({ start }),
+    setEnd: (end) => setQuiet({ end }),
+    adoptDeviceTimeZone: () => (device ? setQuiet({ timeZone: device }) : undefined),
+    saving,
+    disabled: status !== "ready",
+    copy,
+  };
+}
+
+/** The privacy part (rung 4). */
+export function usePrivacyPreviews(copy: NotificationSettingsCopy = DEFAULT_COPY): PrivacyPartProps {
+  const { preferences, saving, update, status } = useNotificationPreferences();
+  return {
+    hidePreviews: preferences.hidePreviews,
+    setHidePreviews: (hidePreviews) => void update((p) => ({ ...p, hidePreviews })),
+    saving,
+    disabled: status !== "ready",
+    copy,
+  };
+}
+
+const minuteStore = {
+  subscribe(listener: () => void) {
+    const timer = setInterval(listener, 30_000);
+    return () => clearInterval(timer);
+  },
+  get: () => Math.floor(Date.now() / 60_000) * 60_000,
+};
+function useMinute(): number {
+  return useSyncExternalStore(minuteStore.subscribe, minuteStore.get, minuteStore.get);
+}
+
+function toggle(id: string, label: string, checked: boolean, onChange: (on: boolean) => void, disabled = false): ReactNode {
+  return (
+    <NativeSwitch
+      testID={`notification-settings-${id}-switch`}
+      accessibilityLabel={label}
+      checked={checked}
+      onCheckedChange={onChange}
+      disabled={disabled}
+    />
+  );
+}
+
+/** The permission part's default rows. */
+export function permissionRows(p: PermissionPartProps): SettingsPageRow[] {
+  const { status, copy } = p;
+  const row: SettingsPageRow = { id: "allow", title: copy.allow, subtitle: copy.status[status], testID: "notification-settings-allow" };
+  if (status === "undetermined") {
+    return [{ ...row, showChevron: true, onPress: p.requesting ? undefined : p.request, disabled: p.requesting, subtitle: `${copy.status.undetermined} · ${copy.turnOn}` }];
+  }
+  if (status === "denied" && p.openSettings) {
+    return [{ ...row, showChevron: true, onPress: p.openSettings, subtitle: `${copy.status.denied} · ${copy.openSettings}` }];
+  }
+  return [row];
+}
+
+/** The categories part's default rows. */
+export function categoryRows(p: CategoriesPartProps): SettingsPageRow[] {
+  return p.categories.map((c) => ({
+    id: `category-${c.id}`,
+    title: c.title,
+    subtitle: c.description,
+    testID: `notification-settings-category-${c.id}`,
+    trailing: toggle(`category-${c.id}`, c.title, c.on, (on) => p.setOn(c.id, on), p.disabled),
+  }));
+}
+
+/** The quiet-hours part's default rows. */
+export function quietHoursRows(p: QuietHoursPartProps): SettingsPageRow[] {
+  const { copy } = p;
+  const rows: SettingsPageRow[] = [
+    {
+      id: "quiet-hours",
+      title: copy.quietHours,
+      subtitle: p.enabled && p.activeNow ? copy.quietHoursOnNow : undefined,
+      testID: "notification-settings-quiet-hours",
+      trailing: toggle("quiet-hours", copy.quietHours, p.enabled, p.setEnabled, p.disabled || (!p.enabled && !p.timeZone && !p.deviceTimeZone)),
+    },
+  ];
+  if (!p.enabled) return rows;
+  const picker = (id: string, label: string, value: string, set: (clock: string) => void) => (
+    <NativeTimePicker testID={`notification-settings-${id}-time`} value={dateAt(value)} onChange={(d) => set(clockOf(d))} formatLabel={() => value} disabled={p.disabled} />
+  );
+  rows.push(
+    { id: "quiet-from", title: copy.from, testID: "notification-settings-quiet-from", trailing: picker("quiet-from", copy.from, p.start, p.setStart) },
+    { id: "quiet-to", title: copy.to, testID: "notification-settings-quiet-to", trailing: picker("quiet-to", copy.to, p.end, p.setEnd) },
+    {
+      id: "time-zone",
+      title: copy.timeZone,
+      subtitle: p.timeZone ? (p.deviceTimeZone ? `${p.timeZone} · ${copy.useDeviceTimeZone} (${p.deviceTimeZone})` : p.timeZone) : copy.noTimeZone,
+      testID: "notification-settings-time-zone",
+      ...(p.deviceTimeZone && !p.disabled ? { onPress: p.adoptDeviceTimeZone, showChevron: true } : {}),
+    },
+  );
+  return rows;
+}
+
+/** The privacy part's default rows. */
+export function privacyRows(p: PrivacyPartProps): SettingsPageRow[] {
+  return [
+    {
+      id: "previews",
+      title: p.copy.showPreviews,
+      testID: "notification-settings-previews",
+      trailing: toggle("previews", p.copy.showPreviews, !p.hidePreviews, (show) => p.setHidePreviews(!show), p.disabled),
+    },
+  ];
+}
+
+export interface NotificationSettingsProps {
+  /** Your words: any of `notificationSettingsCopy`'s, replaced. */
+  copy?: Partial<NotificationSettingsCopy>;
+  /** Replace a part (rendered in its section) or drop its section (`null`). */
+  slots?: Slots<NotificationSettingsSlots>;
+  /** More props for a part, merged over what the screen passes. */
+  slotProps?: SlotPropsFor<NotificationSettingsSlots>;
+  /** Passed to SettingsPage (its own `slots` and `slotProps` reach rows and headers). */
+  page?: Omit<SettingsPageProps, "sections" | "children">;
+  /** Above the first section. */
+  children?: ReactNode;
+  testID?: string;
+}
+
+function section<P extends object>(
+  id: string,
+  title: string,
+  footnote: string | undefined,
+  props: P,
+  rows: (props: P) => SettingsPageRow[],
+  slot: ComponentType<P> | null | undefined,
+  extra: Partial<P> | undefined,
+): SettingsPageSection | null {
+  if (slot === null) return null;
+  const merged = { ...props, ...extra } as P;
+  if (slot) {
+    const Part = slot;
+    return { id, title, footnote, rows: [], children: <Part {...merged} /> };
+  }
+  return { id, title, footnote, rows: rows(merged) };
+}
+
+/** The notification preferences screen. Needs the push block (in GenesisNativeApp's `blocks`, or a `PushProvider`). */
+export function NotificationSettings({ copy: overrides, slots = {}, slotProps = {}, page, children, testID = "notification-settings" }: NotificationSettingsProps) {
+  const copy = useMemo(() => ({ ...DEFAULT_COPY, ...overrides, status: { ...DEFAULT_COPY.status, ...overrides?.status } }), [overrides]);
+  const block = usePush();
+  const permission = usePushPermission(copy);
+  const categories = useNotificationCategories(copy);
+  const quietHours = useQuietHours(copy);
+  const privacy = usePrivacyPreviews(copy);
+  const { error, status } = useNotificationPreferences();
+  const { userId } = useSession();
+  // A load that failed is tried again whenever the screen opens (the block also loads on sign-in).
+  useEffect(() => {
+    if (block.preferences.getState().status === "error" && userId) void block.preferences.load(userId);
+  }, [block, userId]);
+
+  const sections = [
+    section("permission", copy.permissionSection, permission.problem ?? (status === "error" ? copy.loadFailed : error ? copy.saveFailed : undefined), permission, permissionRows, slots.permission, slotProps.permission),
+    block.categories.length > 0
+      ? section("categories", copy.categoriesSection, copy.categoriesFootnote, categories, categoryRows, slots.categories, slotProps.categories)
+      : null,
+    section("quiet-hours", copy.quietHoursSection, copy.quietHoursFootnote, quietHours, quietHoursRows, slots.quietHours, slotProps.quietHours),
+    section("privacy", copy.privacySection, copy.previewsFootnote, privacy, privacyRows, slots.privacy, slotProps.privacy),
+  ].filter((s): s is SettingsPageSection => s !== null);
+
+  return (
+    <SettingsPage testID={testID} {...page} sections={sections}>
+      {children}
+    </SettingsPage>
+  );
+}