@marktiderman/genesis-native 0.1.0 → 0.3.0

package/src/errors.tsx

@@ -0,0 +1,195 @@
+/**
+ * Errors: a boundary per screen tree, and handlers for errors React never sees
+ * (a fatal global error from `ErrorUtils`, an unhandled promise rejection).
+ * All of them report through one `onError` (wire Sentry there) and show the
+ * fatal screen instead of letting the app die; its "Try again" remounts the
+ * tree with fresh state.
+ */
+import { Component, type ComponentType, type ErrorInfo, type ReactNode } from "react";
+import { Pressable, Text, View } from "react-native";
+import { NativeButton, NativeEmptyState } from "@marktiderman/genesis-ui-native/components";
+import { toError } from "./boot";
+
+export interface FatalScreenProps {
+  error: Error;
+  /** Clears the error and remounts the app below the shell (and re-runs a failed boot). */
+  retry: () => void;
+}
+
+/** The default fatal screen: what went wrong and "Try again". */
+export function FatalScreen({ error, retry }: FatalScreenProps) {
+  return (
+    <NativeEmptyState
+      variant="error"
+      title="Something went wrong"
+      body="The app hit a problem. Try again, and if it keeps happening, close and reopen the app."
+      details={error.message}
+      primaryAction={
+        <NativeButton onPress={retry} testID="genesis-fatal-retry">
+          Try again
+        </NativeButton>
+      }
+      testID="genesis-fatal"
+    />
+  );
+}
+
+/**
+ * The last-resort fatal screen: React Native primitives only, no theme, no
+ * context, nothing that can itself fail. Shown when the providers could not
+ * start, or when the `fatal` slot threw.
+ */
+export function PlainFatalScreen({ error, retry }: FatalScreenProps) {
+  return (
+    <View testID="genesis-fatal-plain" style={{ flex: 1, justifyContent: "center", alignItems: "center", padding: 24, gap: 12 }}>
+      <Text accessibilityRole="header" style={{ fontSize: 17, fontWeight: "600" }}>
+        Something went wrong
+      </Text>
+      <Text style={{ textAlign: "center" }}>{error.message}</Text>
+      <Pressable accessibilityRole="button" onPress={retry} testID="genesis-fatal-plain-retry" style={{ padding: 12 }}>
+        <Text style={{ fontSize: 17 }}>Try again</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+export interface ErrorReport {
+  /** True when the app could not go on (a render error, a failed boot, a fatal global error). */
+  fatal: boolean;
+  source: "boundary" | "global" | "boot" | "rejection";
+  componentStack?: string;
+}
+
+export type OnError = (error: Error, report: ErrorReport) => void;
+
+export interface GenesisErrorBoundaryProps {
+  children?: ReactNode;
+  /** What to render instead of the tree that threw. */
+  fallback: ComponentType<FatalScreenProps>;
+  onError?: OnError;
+  /** Change it to clear a caught error (the tree remounts). */
+  resetKey?: unknown;
+  /** Called by the fallback's retry, after the error is cleared. */
+  onRetry?: () => void;
+}
+
+interface BoundaryState {
+  error: Error | null;
+}
+
+/** An error boundary whose fallback gets `{ error, retry }`. */
+export class GenesisErrorBoundary extends Component<GenesisErrorBoundaryProps, BoundaryState> {
+  override state: BoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: unknown): BoundaryState {
+    return { error: toError(error) };
+  }
+
+  override componentDidCatch(error: unknown, info: ErrorInfo) {
+    this.props.onError?.(toError(error), { fatal: true, source: "boundary", componentStack: info.componentStack ?? undefined });
+  }
+
+  override componentDidUpdate(previous: GenesisErrorBoundaryProps) {
+    if (this.state.error && previous.resetKey !== this.props.resetKey) this.setState({ error: null });
+  }
+
+  retry = () => {
+    this.setState({ error: null });
+    this.props.onRetry?.();
+  };
+
+  override render() {
+    const { error } = this.state;
+    if (!error) return this.props.children ?? null;
+    const Fallback = this.props.fallback;
+    return <Fallback error={error} retry={this.retry} />;
+  }
+}
+
+/** React Native's `ErrorUtils` (a global in every RN app), or a stand-in. */
+export interface ErrorUtilsLike {
+  getGlobalHandler(): ((error: unknown, isFatal?: boolean) => void) | undefined;
+  setGlobalHandler(handler: (error: unknown, isFatal?: boolean) => void): void;
+}
+
+export interface GlobalErrorHandlerOptions {
+  errorUtils: ErrorUtilsLike;
+  onError?: OnError;
+  /** A fatal error: show the fatal screen. The previous handler (which would end the app) is not called. */
+  onFatal: (error: Error) => void;
+  /**
+   * True while a fatal screen is already up. Another fatal error then goes to
+   * the previous handler, which ends the app (it restarts clean) rather than
+   * leaving it stuck behind a screen that may itself be broken.
+   */
+  alreadyFatal?: () => boolean;
+}
+
+/**
+ * Route global errors to `onError`. A fatal one goes to `onFatal` instead of
+ * React Native's default handler, which would close the app; a non-fatal one
+ * still reaches the previous handler (LogBox in development). Returns a
+ * function that puts the previous handler back.
+ */
+export function installGlobalErrorHandler({ errorUtils, onError, onFatal, alreadyFatal }: GlobalErrorHandlerOptions): () => void {
+  const previous = errorUtils.getGlobalHandler();
+  errorUtils.setGlobalHandler((raw, isFatal) => {
+    const error = toError(raw);
+    try {
+      onError?.(error, { fatal: Boolean(isFatal), source: "global" });
+    } catch {
+      // A failing reporter must not take the handler down with it.
+    }
+    if (isFatal && !alreadyFatal?.()) onFatal(error);
+    else previous?.(raw, isFatal);
+  });
+  return () => {
+    // With no previous handler, leave one that only logs, never ours (it would call an unmounted app).
+    errorUtils.setGlobalHandler(previous ?? ((error) => console.error(error)));
+  };
+}
+
+/** `globalThis.ErrorUtils` in a React Native runtime, undefined elsewhere. */
+export function defaultErrorUtils(): ErrorUtilsLike | undefined {
+  const candidate = (globalThis as { ErrorUtils?: ErrorUtilsLike }).ErrorUtils;
+  return candidate && typeof candidate.setGlobalHandler === "function" ? candidate : undefined;
+}
+
+/** Hermes's `HermesInternal.enablePromiseRejectionTracker`, or a stand-in. */
+export type EnableRejectionTracker = (options: {
+  allRejections: boolean;
+  onUnhandled: (id: number, rejection: unknown) => void;
+  onHandled: (id: number) => void;
+}) => void;
+
+/**
+ * Hermes's rejection tracker, when the app runs on Hermes. React Native sends
+ * unhandled rejections to `ExceptionsManager` (LogBox in development), never
+ * to `ErrorUtils`' global handler, so without this they never reach `onError`.
+ */
+export function defaultRejectionTracker(): EnableRejectionTracker | undefined {
+  const hermes = (globalThis as { HermesInternal?: { enablePromiseRejectionTracker?: EnableRejectionTracker } }).HermesInternal;
+  const enable = hermes?.enablePromiseRejectionTracker;
+  return typeof enable === "function" ? enable.bind(hermes) : undefined;
+}
+
+/**
+ * Report unhandled promise rejections to `onError` (non-fatal). This replaces
+ * React Native's own tracker, so each rejection is also written with
+ * `console.warn`, which LogBox shows in development as before.
+ */
+export function installRejectionTracker({ enable, onError }: { enable: EnableRejectionTracker; onError: OnError }): void {
+  enable({
+    allRejections: true,
+    onUnhandled: (id, rejection) => {
+      const error = toError(rejection);
+      console.warn(`Uncaught (in promise, id: ${id}): ${error.message}`);
+      try {
+        onError(error, { fatal: false, source: "rejection" });
+      } catch {
+        // A failing reporter must not throw inside the promise machinery.
+      }
+    },
+    onHandled: () => {},
+  });
+}

package/src/held-link.ts

@@ -0,0 +1,90 @@
+/**
+ * Hold a deep link until sign-in completes.
+ *
+ * expo-router opens every incoming link itself. For a signed-in user that is
+ * all that should happen. For a signed-out user, the auth layout redirects to
+ * sign-in and the link is lost; holding it lets the app go there once the user
+ * has signed in. The hold lives outside React, because expo-router's
+ * `+native-intent` runs before any component:
+ *
+ *   // lib/links.ts
+ *   export const linkHold = createLinkHold();
+ *   // app/+native-intent.ts
+ *   export function redirectSystemPath({ path }) {
+ *     const to = normalizeLink(path, links);
+ *     if (to && to !== "/") linkHold.hold(to);
+ *     return to;
+ *   }
+ *
+ * `useHeldLink` follows a held link only if the user was seen signed out
+ * while it was held. A link that arrives while signed in, or at a cold start
+ * that turns out signed in, is dropped, since the router already opened it.
+ * `GenesisNativeApp` runs it for you (`links.onRelease`).
+ */
+import { useEffect, useRef, useSyncExternalStore } from "react";
+
+export interface LinkHold {
+  /** Hold `path`, replacing any held one. */
+  hold(path: string): void;
+  peek(): string | null;
+  /** Return the held path and forget it. */
+  take(): string | null;
+  clear(): void;
+  subscribe(listener: () => void): () => void;
+}
+
+/** A place to hold one deep link until sign-in completes; lives outside React. */
+export function createLinkHold(): LinkHold {
+  let held: string | null = null;
+  const listeners = new Set<() => void>();
+  const set = (next: string | null) => {
+    if (held === next) return;
+    held = next;
+    for (const listener of listeners) listener();
+  };
+  return {
+    hold: (path) => set(path),
+    peek: () => held,
+    take() {
+      const path = held;
+      set(null);
+      return path;
+    },
+    clear: () => set(null),
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+/** `"pending"` while booting or reading the session. */
+export type HeldLinkAuth = "pending" | "signedOut" | "signedIn";
+
+export interface UseHeldLinkOptions {
+  auth: HeldLinkAuth;
+  /** Go there, e.g. `(path) => router.replace(path)`. Called once per link held across a sign-in. */
+  onRelease: (path: string) => void;
+}
+
+/** Follow the held link after a sign-in, drop it otherwise; returns the link still held. */
+export function useHeldLink(hold: LinkHold, { auth, onRelease }: UseHeldLinkOptions): string | null {
+  const held = useSyncExternalStore(hold.subscribe, hold.peek, hold.peek);
+  const release = useRef(onRelease);
+  release.current = onRelease;
+  // Was the user signed out while this link was held?
+  const waitedForSignIn = useRef(false);
+  useEffect(() => {
+    if (held === null) {
+      waitedForSignIn.current = false;
+      return;
+    }
+    if (auth === "signedOut") waitedForSignIn.current = true;
+    if (auth !== "signedIn") return;
+    const path = hold.take();
+    const follow = waitedForSignIn.current;
+    waitedForSignIn.current = false;
+    if (path !== null && follow) release.current(path);
+  }, [auth, held, hold]);
+  return held;
+}

package/src/hydration-gate.ts

@@ -0,0 +1,88 @@
+/**
+ * A hydration gate holds writes until a persisted store has loaded from disk.
+ *
+ * The bug it prevents: a persisted store (zustand `persist`, say) is created
+ * with defaults, something sets a value before the saved state has been read,
+ * and that write lands on disk first, replacing what the user had. With the
+ * gate, a write made before hydration never reaches disk (`storage()`), or
+ * waits for it (`run()`).
+ *
+ *   const gate = createHydrationGate();
+ *   persist(store, {
+ *     storage: createJSONStorage(() => gate.storage(AsyncStorage)),
+ *     // Open only after a good read: after a failed one, writes would replace what's on disk.
+ *     onRehydrateStorage: () => (_state, error) => {
+ *       if (!error) gate.markHydrated();
+ *     },
+ *   });
+ */
+import type { AsyncStorageLike } from "./query";
+
+export interface HydrationGate {
+  readonly hydrated: boolean;
+  /** Call once the store has read its saved state. Idempotent. */
+  markHydrated(): void;
+  /** Resolves once hydrated. */
+  whenHydrated(): Promise<void>;
+  /** Run a write now if hydrated, otherwise once hydrated. */
+  run<T>(write: () => T | Promise<T>): Promise<T>;
+  /**
+   * The storage, with writes made before hydration dropped (reads pass
+   * through, since hydration is a read). After hydration the store writes
+   * its merged state on its next change, so nothing is lost but the stale
+   * write. (A zustand migration's own write during hydration is dropped too;
+   * the old version stays on disk and is migrated again until then.)
+   */
+  storage<S extends AsyncStorageLike>(storage: S): S;
+}
+
+export interface HydrationGateOptions {
+  /** Told about each write `storage()` dropped (to log it in development). */
+  onDroppedWrite?: (key: string) => void;
+}
+
+/** A gate that holds writes until a persisted store has hydrated. */
+export function createHydrationGate({ onDroppedWrite }: HydrationGateOptions = {}): HydrationGate {
+  let hydrated = false;
+  let open!: () => void;
+  const opened = new Promise<void>((resolve) => {
+    open = resolve;
+  });
+
+  const gate: HydrationGate = {
+    get hydrated() {
+      return hydrated;
+    },
+    markHydrated() {
+      if (hydrated) return;
+      hydrated = true;
+      open();
+    },
+    whenHydrated: () => opened,
+    async run(write) {
+      if (!hydrated) await opened;
+      return write();
+    },
+    storage(storage) {
+      const setItem = async (key: string, value: string) => {
+        if (!hydrated) return onDroppedWrite?.(key);
+        return storage.setItem(key, value);
+      };
+      const removeItem = async (key: string) => {
+        if (!hydrated) return onDroppedWrite?.(key);
+        return storage.removeItem(key);
+      };
+      // A proxy, not a spread: a storage class's prototype methods (and its
+      // private fields, through `this`) keep working.
+      return new Proxy(storage, {
+        get(target, property) {
+          if (property === "setItem") return setItem;
+          if (property === "removeItem") return removeItem;
+          const value = Reflect.get(target, property, target) as unknown;
+          return typeof value === "function" ? value.bind(target) : value;
+        },
+      });
+    },
+  };
+  return gate;
+}

package/src/index.ts

@@ -0,0 +1,83 @@
+/**
+ * @marktiderman/genesis-native — the native app shell.
+ *
+ * Rung 1: `<GenesisNativeApp>`. Rung 2: its `slots` / `slotProps`.
+ * Rungs 3 and 4: each part below on its own, as a primitive and a hook.
+ * Query persistence is in `@marktiderman/genesis-native/persist`.
+ *
+ * @stability Beta
+ */
+export {
+  GenesisNativeApp,
+  type GenesisNativeAppProps,
+  type NativeAppSlots,
+  type NativeQueryClientOptions,
+  BootScreen,
+  type SplashModule,
+  type BootScreenProps,
+  type SignedOutProps,
+} from "./app";
+export {
+  createBoot,
+  BootProvider,
+  useBoot,
+  BootTimeoutError,
+  type BootController,
+  type BootOptions,
+  type BootState,
+  type BootStatus,
+  type BootStep,
+  type BootStepContext,
+  type UseBootReturn,
+} from "./boot";
+export {
+  FatalScreen,
+  PlainFatalScreen,
+  GenesisErrorBoundary,
+  installGlobalErrorHandler,
+  installRejectionTracker,
+  defaultErrorUtils,
+  defaultRejectionTracker,
+  type EnableRejectionTracker,
+  type ErrorReport,
+  type ErrorUtilsLike,
+  type FatalScreenProps,
+  type GenesisErrorBoundaryProps,
+  type GlobalErrorHandlerOptions,
+  type OnError,
+} from "./errors";
+export {
+  createNativeQueryClient,
+  connectQueryLifecycle,
+  DAY_MS,
+  type AppStateLike,
+  type AsyncStorageLike,
+  type NetInfoLike,
+  type QueryLifecycleOptions,
+  type QueryPersistence,
+} from "./query";
+export { createHydrationGate, type HydrationGate, type HydrationGateOptions } from "./hydration-gate";
+export {
+  AuthGate,
+  SessionProvider,
+  createSessionStore,
+  useSession,
+  type AuthClientLike,
+  type AuthGateProps,
+  type SessionState,
+  type SessionStatus,
+  type SessionStore,
+  type SessionStoreOptions,
+} from "./auth";
+export { normalizeLink, type LinkOptions, type LinkTarget } from "./links";
+export { createLinkHold, useHeldLink, type HeldLinkAuth, type LinkHold, type UseHeldLinkOptions } from "./held-link";
+export {
+  useBlocks,
+  useBlockSettings,
+  mergeBlockSettings,
+  type BlockSettingsSection,
+  type NativeBlock,
+  type NativeBlockRootProps,
+  type SettingsRowLike,
+  type UseBlockSettingsOptions,
+} from "./blocks";

package/src/links.ts

@@ -0,0 +1,140 @@
+/**
+ * Deep links: turn an incoming universal link or app link into an app path.
+ *
+ * Meant for expo-router's `app/+native-intent.ts`:
+ *
+ *   export function redirectSystemPath({ path }: { path: string }) {
+ *     return normalizeLink(path, links);
+ *   }
+ *
+ * A link to a path the map doesn't know goes to `"/"` (and `onUnknown`), so a
+ * stale or mistyped link opens the app instead of a "not found" screen. It
+ * never throws: anything it can't read is unknown.
+ */
+
+/** A target path (`"/clients/:id"`, params filled in) or a function of the params. */
+export type LinkTarget = string | ((params: Record<string, string>) => string);
+
+export interface LinkOptions {
+  /** App schemes, without `://` (`["myapp"]`). `myapp://clients/1` is the path `/clients/1`. */
+  schemes?: readonly string[];
+  /** Hosts of universal / app links (`["example.com"]`). Other hosts are unknown. */
+  hosts?: readonly string[];
+  /**
+   * Incoming path pattern → app path. A segment `:name` captures one
+   * segment, a final `*` captures the rest (as `params["*"]`). The first
+   * match wins; `"/"` is always known.
+   */
+  map: Readonly<Record<string, LinkTarget>>;
+  /** Patterns to ignore (return `null`, so expo-router doesn't navigate), e.g. an auth callback. */
+  ignore?: readonly string[];
+  /** Told about each link that went to `"/"` because nothing matched. */
+  onUnknown?: (url: string) => void;
+}
+
+const URL_PATTERN = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)([^?#]*)(\?[^#]*)?(#.*)?$/i;
+
+interface Parsed {
+  path: string;
+  query: string;
+}
+
+function parse(url: string, schemes: readonly string[], hosts: readonly string[]): Parsed | null {
+  const trimmed = url.trim();
+  const match = URL_PATTERN.exec(trimmed);
+  if (!match) {
+    // Already a path (expo-router passes paths as well as URLs).
+    if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return null;
+    const noHash = trimmed.split("#")[0] ?? "";
+    const at = noHash.indexOf("?");
+    return at < 0 ? { path: noHash, query: "" } : { path: noHash.slice(0, at), query: noHash.slice(at) };
+  }
+  const [, scheme = "", host = "", path = "", query = ""] = match;
+  const lowerScheme = scheme.toLowerCase();
+  if (lowerScheme === "http" || lowerScheme === "https") {
+    const bareHost = host.toLowerCase().replace(/:\d+$/, "");
+    if (!hosts.some((h) => h.toLowerCase() === bareHost)) return null;
+    return { path, query };
+  }
+  if (!schemes.some((s) => s.toLowerCase() === lowerScheme)) return null;
+  // In `myapp://clients/1`, "clients" sits where a host would.
+  return { path: `/${host}${path}`, query };
+}
+
+function clean(path: string): string {
+  const joined = `/${path}`.replace(/\/{2,}/g, "/");
+  return joined.length > 1 ? joined.replace(/\/$/, "") : joined;
+}
+
+function matchPattern(pattern: string, path: string): Record<string, string> | null {
+  const want = clean(pattern).split("/").slice(1);
+  const have = path.split("/").slice(1);
+  const params: Record<string, string> = {};
+  for (let i = 0; i < want.length; i++) {
+    const segment = want[i]!;
+    if (segment === "*" && i === want.length - 1) {
+      params["*"] = have.slice(i).join("/");
+      return params;
+    }
+    const value = have[i];
+    if (value === undefined) return null;
+    if (segment.startsWith(":")) params[segment.slice(1)] = value;
+    else if (segment !== value) return null;
+  }
+  return want.length === have.length ? params : null;
+}
+
+function fill(target: LinkTarget, params: Record<string, string>): string {
+  if (typeof target === "function") return target(params);
+  return target.replace(/:([A-Za-z_][A-Za-z0-9_]*)|\*$/g, (token, name: string | undefined) =>
+    name === undefined ? (params["*"] ?? "") : (params[name] ?? token),
+  );
+}
+
+function isDotSegment(segment: string): boolean {
+  let decoded = segment;
+  try {
+    decoded = decodeURIComponent(segment);
+  } catch {
+    // Malformed escapes stay as they are.
+  }
+  return decoded === "." || decoded === "..";
+}
+
+function withQuery(path: string, query: string): string {
+  if (!query || query === "?") return path;
+  return path.includes("?") ? `${path}&${query.slice(1)}` : `${path}${query}`;
+}
+
+/** The app path for `url`, `"/"` when it is unknown, or `null` when it is ignored. */
+export function normalizeLink(url: string, options: LinkOptions): string | null {
+  const { schemes = [], hosts = [], map, ignore = [], onUnknown } = options;
+  const unknown = () => {
+    onUnknown?.(url);
+    return "/";
+  };
+  let parsed: Parsed | null;
+  try {
+    parsed = parse(url, schemes, hosts);
+  } catch {
+    parsed = null;
+  }
+  if (!parsed) return unknown();
+  const path = clean(parsed.path);
+  // "." and ".." would let a link climb out of the path it matched (a `*` capture included).
+  if (path.split("/").some(isDotSegment)) {
+    return unknown();
+  }
+  if (ignore.some((pattern) => matchPattern(pattern, path))) return null;
+  if (path === "/") return withQuery("/", parsed.query);
+  for (const [pattern, target] of Object.entries(map)) {
+    const params = matchPattern(pattern, path);
+    if (!params) continue;
+    try {
+      return withQuery(fill(target, params), parsed.query);
+    } catch {
+      return unknown();
+    }
+  }
+  return unknown();
+}

package/src/nativewind.d.ts

@@ -0,0 +1,41 @@
+// NativeWind className augmentation for react-native types.
+// This adds className to RN component props so ui-native components
+// typecheck correctly both standalone and when consumed by apps.
+// The top-level import makes this a module augmentation (not an ambient declaration),
+// so it merges with the real react-native types rather than replacing them.
+
+// This import is required to make this file a module augmentation (not an ambient declaration).
+// Removing it silently changes the semantics from "merge with" to "replace" the react-native types.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type { AnimatedProps } from "react-native";
+
+declare module "react-native" {
+  interface ViewProps {
+    className?: string;
+  }
+  interface TextProps {
+    className?: string;
+  }
+  interface TextInputProps {
+    className?: string;
+  }
+  interface ImageProps {
+    className?: string;
+  }
+  interface ImagePropsBase {
+    className?: string;
+  }
+  interface PressableProps {
+    className?: string;
+  }
+  interface SwitchProps {
+    className?: string;
+  }
+  interface ScrollViewProps {
+    className?: string;
+    contentContainerClassName?: string;
+  }
+  interface TouchableWithoutFeedbackProps {
+    className?: string;
+  }
+}