User-Facing Error Copy

// src/errors/userMessages.ts
export type UserFacingError = {
  title: string;
  body: string;
  action: "retry" | "settings" | "support" | "dismiss";
  actionLabel: string;
};
 
const NETWORK: UserFacingError = {
  title: "You're offline",
  body: "Check your connection and try again. Your changes are saved on this device.",
  action: "retry",
  actionLabel: "Try again",
};
 
const UNKNOWN: UserFacingError = {
  title: "Something went wrong",
  body: "We could not complete that. Try again in a moment.",
  action: "retry",
  actionLabel: "Try again",
};
 
export function toUserFacingError(error: unknown): UserFacingError {
  if (error instanceof TypeError && /network/i.test(error.message)) {
    return NETWORK;
  }
  if (isHttpError(error, 401)) {
    return {
      title: "Session expired",
      body: "Sign in again to continue.",
      action: "dismiss",
      actionLabel: "Sign in",
    };
  }
  if (isHttpError(error, 503)) {
    return {
      title: "Service busy",
      body: "Our servers are temporarily overloaded. Wait a few seconds and retry.",
      action: "retry",
      actionLabel: "Try again",
    };
  }
  return UNKNOWN;
}
 
function isHttpError(error: unknown, status: number): boolean {
  return (
    typeof error === "object" &&
    error !== null &&
    "status" in error &&
    (error as { status: number }).status === status
  );
}

// src/components/ErrorCallout.tsx
import { Button, StyleSheet, Text, View } from "react-native";
import type { UserFacingError } from "@/errors/userMessages";
 
type Props = {
  error: UserFacingError;
  onAction: () => void;
};
 
export function ErrorCallout({ error, onAction }: Props) {
  return (
    <View
      style={styles.box}
      accessibilityRole="alert"
      accessibilityLiveRegion="polite"
    >
      <Text style={styles.title}>{error.title}</Text>
      <Text style={styles.body}>{error.body}</Text>
      <Button title={error.actionLabel} onPress={onAction} />
    </View>
  );
}
 
const styles = StyleSheet.create({
  box: {
    padding: 16,
    borderRadius: 8,
    backgroundColor: "#fef2f2",
    borderWidth: StyleSheet.hairlineWidth,
    borderColor: "#fecaca",
    gap: 8,
  },
  title: { fontSize: 16, fontWeight: "700", color: "#991b1b" },
  body: { color: "#7f1d1d", lineHeight: 20 },
});

// src/errors/reportError.ts
import type { UserFacingError } from "./userMessages";
 
export function reportError(
  scope: string,
  cause: unknown,
  user: UserFacingError,
): void {
  if (__DEV__) {
    console.group(`[${scope}]`);
    console.error(cause);
    console.log("User copy:", user);
    console.groupEnd();
    return;
  }
  // Production: Sentry/Crashlytics with scope + cause; never attach user.title to analytics PII
}
 
// src/screens/ProfileScreen.tsx
import { useCallback, useEffect, useState } from "react";
import {
  ActivityIndicator,
  Button,
  StyleSheet,
  Text,
  View,
} from "react-native";
import { ErrorCallout } from "@/components/ErrorCallout";
import { reportError } from "@/errors/reportError";
import { toUserFacingError } from "@/errors/userMessages";
 
async function fetchProfile(): Promise<{ name: string }> {
  const response = await fetch("https://api.example.com/me");
  if (!response.ok) {
    throw { status: response.status, message: await response.text() };
  }
  return (await response.json()) as { name: string };
}
 
export function ProfileScreen() {
  const [name, setName] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);
  const [userError, setUserError] = useState<ReturnType<
    typeof toUserFacingError
  > | null>(null);
 
  const load = useCallback(async () => {
    setLoading(true);
    setUserError(null);
    try {
      const data = await fetchProfile();
      setName(data.name);
    } catch (cause) {
      const user = toUserFacingError(cause);
      setUserError(user);
      reportError("ProfileScreen.load", cause, user);
    } finally {
      setLoading(false);
    }
  }, []);
 
  useEffect(() => {
    void load();
  }, [load]);
 
  if (loading) {
    return <ActivityIndicator accessibilityLabel="Loading profile" />;
  }
 
  if (userError) {
    return (
      <View style={styles.screen}>
        <ErrorCallout
          error={userError}
          onAction={() => {
            if (userError.action === "retry") void load();
            // wire sign-in / support / settings per action enum
          }}
        />
      </View>
    );
  }
 
  return (
    <View style={styles.screen}>
      <Text style={styles.title}>Hello, {name}</Text>
      <Button title="Refresh" onPress={() => void load()} />
    </View>
  );
}
 
const styles = StyleSheet.create({
  screen: { flex: 1, padding: 24, justifyContent: "center", gap: 12 },
  title: { fontSize: 22, fontWeight: "700" },
});
 
// src/components/ScreenErrorBoundary.tsx - boundary copy matches the same tone
import { Component, type ReactNode } from "react";
import { Button, StyleSheet, Text, View } from "react-native";
 
type Props = { children: ReactNode };
type State = { hasError: boolean };
 
export class ScreenErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false };
 
  static getDerivedStateFromError(): State {
    return { hasError: true };
  }
 
  componentDidCatch(error: Error) {
    if (__DEV__) console.error(error);
    // report to crash service in production
  }
 
  render() {
    if (this.state.hasError) {
      return (
        <View style={boundaryStyles.wrap} accessibilityRole="alert">
          <Text style={boundaryStyles.title}>This screen hit a snag</Text>
          <Text style={boundaryStyles.body}>
            The rest of the app still works. Try again or go back.
          </Text>
          <Button
            title="Try again"
            onPress={() => this.setState({ hasError: false })}
          />
        </View>
      );
    }
    return this.props.children;
  }
}
 
const boundaryStyles = StyleSheet.create({
  wrap: { flex: 1, justifyContent: "center", padding: 24, gap: 12 },
  title: { fontSize: 18, fontWeight: "700" },
  body: { color: "#64748b", lineHeight: 22 },
});

export function DevDiagnostics({ error }: { error: unknown }) {
  if (!__DEV__) return null;
  return (
    <Text style={{ fontFamily: "monospace", fontSize: 11 }}>
      {error instanceof Error ? error.stack : String(error)}
    </Text>
  );
}

// Keep action handling exhaustive
function handleErrorAction(
  user: UserFacingError,
  handlers: Record<UserFacingError["action"], () => void>,
) {
  handlers[user.action]();
}