@marktiderman/genesis-native 0.2.0 → 0.4.0

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>
+  );
+}

package/src/query.ts

@@ -0,0 +1,100 @@
+/**
+ * Query: a TanStack Query client with offline-safe defaults, and the contract
+ * for saving it to the phone. The persister itself is in
+ * `@marktiderman/genesis-native/persist`, so an app that saves nothing doesn't
+ * install TanStack's persister packages.
+ */
+import { QueryClient, focusManager, onlineManager, type QueryClientConfig } from "@tanstack/react-query";
+
+/** The part of AsyncStorage (or any async key-value store) Genesis uses. */
+export interface AsyncStorageLike {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+/** One day in milliseconds: the default max age of the saved query cache. */
+export const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * A QueryClient for a phone. `networkMode: "offlineFirst"` runs a query or
+ * mutation once whatever the network says, then pauses its retries while the
+ * device is offline (`onlineManager`, which `connectQueryLifecycle` feeds from
+ * NetInfo), continues them when it is back, and refetches stale queries on
+ * reconnect. So offline, a query with saved data keeps showing it
+ * (`fetchStatus: "paused"`); one with nothing saved stays `pending` and paused
+ * until the network returns (check `isPaused`, not only `isPending`, before
+ * showing a spinner); and a mutation, which TanStack doesn't retry by default,
+ * fails at once instead of waiting. `gcTime` matches the persisted max age, or
+ * restored queries would be collected before they are used. Your `config` wins.
+ */
+export function createNativeQueryClient(config: QueryClientConfig = {}): QueryClient {
+  const { queries, mutations, ...rest } = config.defaultOptions ?? {};
+  return new QueryClient({
+    ...config,
+    defaultOptions: {
+      ...rest,
+      queries: { networkMode: "offlineFirst", gcTime: DAY_MS, staleTime: 60_000, ...queries },
+      mutations: { networkMode: "offlineFirst", ...mutations },
+    },
+  });
+}
+
+/**
+ * The saved query cache. A `scope` (the signed-in user's id, `""` for nobody)
+ * is part of what is saved: a cache saved for one user is discarded, on disk
+ * too, when another scope restores it.
+ */
+export interface QueryPersistence {
+  /** Load the saved cache into the client, if it was saved for `scope`. */
+  restore(scope: string): Promise<void>;
+  /** Save on every cache change, for `scope`; returns the unsubscribe. */
+  subscribe(scope: string): () => void;
+  /**
+   * Delete the saved cache. Clear the QueryClient first: the subscription
+   * then saves the empty cache, so a save already in flight can't leave the
+   * old queries on disk.
+   */
+  clear(): Promise<void>;
+}
+
+/** React Native's `AppState`, or a stand-in. */
+export interface AppStateLike {
+  addEventListener(type: "change", listener: (state: string) => void): { remove(): void };
+}
+
+/** `@react-native-community/netinfo`'s default export, or a stand-in. */
+export interface NetInfoLike {
+  addEventListener(listener: (state: { isConnected: boolean | null }) => void): () => void;
+}
+
+export interface QueryLifecycleOptions {
+  appState?: AppStateLike;
+  netInfo?: NetInfoLike;
+}
+
+/**
+ * Tell TanStack Query when the app comes to the front (refetch stale
+ * queries) and when the network comes and goes. Returns the cleanup.
+ */
+export function connectQueryLifecycle({ appState, netInfo }: QueryLifecycleOptions): () => void {
+  if (appState) {
+    focusManager.setEventListener((setFocused) => {
+      const subscription = appState.addEventListener("change", (state) => setFocused(state === "active"));
+      return () => subscription.remove();
+    });
+  }
+  if (netInfo) {
+    onlineManager.setEventListener((setOnline) => netInfo.addEventListener((state) => setOnline(state.isConnected !== false)));
+  }
+  return () => {
+    // Replacing the listener runs the cleanup of the one set above.
+    if (appState) focusManager.setEventListener(() => () => {});
+    if (netInfo) {
+      onlineManager.setEventListener(() => () => {});
+      // Nothing reports the network any more: don't leave paused queries waiting on the last
+      // "offline" NetInfo said (offlineFirst pauses retries while offline).
+      onlineManager.setOnline(true);
+    }
+  };
+}