@umituz/react-native-settings 4.20.57 → 4.20.59

package/src/presentation/components/SettingsErrorBoundary/README.md

@@ -1,461 +1,67 @@
 # Settings Error Boundary
 
-Error boundary component for catching and handling errors in settings screens and components.
+## Purpose
 
-## Features
+Error boundary component for catching and handling errors in settings screens and components, providing fallback UI and error recovery options.
 
-- **Error Catching**: Catches JavaScript errors in component tree
-- **Fallback UI**: Displays user-friendly error messages
-- **Error Reporting**: Integrates with error tracking services
-- **Recovery Options**: Provide retry or reset actions
-- **Development Mode**: Detailed error info in development
+## File Paths
 
-## Installation
+- **Component**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/components/SettingsErrorBoundary/SettingsErrorBoundary.tsx`
 
-This component is part of `@umituz/react-native-settings`.
+## Strategy
 
-## Usage
+1. **Error Containment**: Catches JavaScript errors in the component tree below it, preventing app crashes
+2. **User-Friendly Fallback**: Displays clear, non-technical error messages to users
+3. **Error Recovery**: Provides retry or reset actions to recover from errors
+4. **Development Support**: Shows detailed error information in development mode for debugging
+5. **Error Reporting**: Integrates with error tracking services for monitoring
 
-### Basic Usage
+## Restrictions (Forbidden)
 
-```tsx
-import { SettingsErrorBoundary } from '@umituz/react-native-settings';
+### DO NOT
+- ❌ DO NOT wrap individual small components (use at screen or major section level)
+- ❌ DO NOT use error boundaries to handle expected errors (e.g., network failures)
+- ❌ DO NOT show technical stack traces to end users in production
 
-function App() {
-  return (
-    <SettingsErrorBoundary>
-      <SettingsScreen />
-    </SettingsErrorBoundary>
-  );
-}
-```
+### NEVER
+- ❌ NEVER use error boundaries inside event handlers or async code
+- ❌ NEVER use error boundaries to control flow or business logic
+- ❌ NEVER expose sensitive information in error messages
 
-### With Custom Fallback
+### AVOID
+- ❌ AVOID nesting multiple error boundaries without clear purpose
+- ❌ AVOID generic error messages that don't help users understand what happened
+- ❌ AVOID blocking the entire app when a recoverable error occurs
 
-```tsx
-function App() {
-  return (
-    <SettingsErrorBoundary
-      fallback={<ErrorFallback />}
-      onError={(error) => console.error(error)}
-    >
-      <SettingsScreen />
-    </SettingsErrorBoundary>
-  );
-}
+## Rules (Mandatory)
 
-function ErrorFallback() {
-  return (
-    <View style={styles.container}>
-      <Text>Something went wrong</Text>
-      <Button title="Retry" onPress={() => window.location.reload()} />
-    </View>
-  );
-}
-```
+### ALWAYS
+- ✅ ALWAYS provide a clear fallback UI when errors occur
+- ✅ ALWAYS log errors for debugging and monitoring
+- ✅ ALWAYS integrate with error tracking services (e.g., Sentry)
+- ✅ ALWAYS show user-friendly error messages in production
 
-### With Recovery Actions
+### MUST
+- ✅ MUST offer recovery options (retry, reset, or navigation) to users
+- ✅ MUST ensure error boundaries don't interfere with normal error handling
+- ✅ MUST test error scenarios during development
 
-```tsx
-function App() {
-  const handleReset = () => {
-    // Clear cache
-    clearSettingsCache();
-    // Reload app
-    Updates.reloadAsync();
-  };
+### SHOULD
+- ✅ SHOULD provide context-specific error messages when possible
+- ✅ SHOULD include development-only error details for debugging
+- ✅ SHOULD offer a way to report errors or contact support
 
-  return (
-    <SettingsErrorBoundary
-      onReset={handleReset}
-      fallback={({ error, resetError }) => (
-        <ErrorFallback error={error} onReset={resetError} />
-      )}
-    >
-      <SettingsScreen />
-    </SettingsErrorBoundary>
-  );
-}
-```
+## AI Agent Guidelines
 
-## Props
+1. **File Reference**: When implementing error handling, refer to `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/components/SettingsErrorBoundary/SettingsErrorBoundary.tsx`
+2. **Placement Strategy**: Place error boundaries at strategic locations (screen level, major feature sections)
+3. **Fallback Design**: Design fallback UIs that match your app's visual design
+4. **Error Tracking**: Always integrate with error tracking services like Sentry or Crashlytics
+5. **Recovery Logic**: Implement appropriate recovery actions based on error type and context
 
-### SettingsErrorBoundaryProps
+## Component Reference
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `ReactNode` | **Required** | Component tree to wrap |
-| `fallback` | `ReactNode \| FallbackRender` | Default fallback | Fallback UI when error occurs |
-| `onError` | `(error: Error) => void` | `undefined` | Error callback |
-| `onReset` | `() => void` | `undefined` | Reset callback |
-| `retryButton` | `boolean` | `true` | Show retry button |
-| `showDetails` | `boolean` | `__DEV__` | Show error details |
-
-### FallbackRender
-
-```typescript
-type FallbackRender = (props: {
-  error: Error;
-  resetError: () => void;
-}) => ReactNode;
-```
-
-## Fallback Component
-
-### Default Fallback
-
-```tsx
-<SettingsErrorBoundary>
-  <SettingsScreen />
-</SettingsErrorBoundary>
-
-// Renders on error:
-// ┌────────────────────────────┐
-// │                            │
-// │      ⚠️ Error              │
-// │                            │
-// │  Something went wrong      │
-// │  while loading settings    │
-// │                            │
-// │      [Try Again]           │
-// │                            │
-// └────────────────────────────┘
-```
-
-### Custom Fallback
-
-```tsx
-function CustomFallback({ error, resetError }) {
-  return (
-    <View style={styles.container}>
-      <View style={styles.iconContainer}>
-        <Ionicons name="alert-circle-outline" size={64} color="red" />
-      </View>
-
-      <Text style={styles.title}>Oops! Something went wrong</Text>
-
-      <Text style={styles.message}>
-        {error.message || 'An unexpected error occurred'}
-      </Text>
-
-      {__DEV__ && (
-        <Text style={styles.details}>
-          {error.stack}
-        </Text>
-      )}
-
-      <Button
-        title="Try Again"
-        onPress={resetError}
-        style={styles.button}
-      />
-
-      <Button
-        title="Go Back"
-        onPress={() => navigation.goBack()}
-        variant="secondary"
-      />
-    </View>
-  );
-}
-```
-
-## Usage Examples
-
-### With Error Reporting
-
-```tsx
-function App() {
-  const reportError = (error: Error) => {
-    // Log to error tracking service
-    Sentry.captureException(error);
-
-    // Log to console
-    console.error('Settings error:', error);
-
-    // Report to analytics
-    Analytics.track('settings_error', {
-      message: error.message,
-      stack: error.stack,
-    });
-  };
-
-  return (
-    <SettingsErrorBoundary onError={reportError}>
-      <SettingsScreen />
-    </SettingsErrorBoundary>
-  );
-}
-```
-
-### With Context Recovery
-
-```tsx
-function SettingsWithRecovery() {
-  const [hasError, setHasError] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  const handleReset = useCallback(() => {
-    setHasError(false);
-    setError(null);
-  }, []);
-
-  if (hasError) {
-    return (
-      <ErrorFallback
-        error={error}
-        onReset={handleReset}
-      />
-    );
-  }
-
-  return (
-    <SettingsErrorBoundary
-      onError={(error) => {
-        setHasError(true);
-        setError(error);
-      }}
-    >
-      <SettingsScreen />
-    </SettingsErrorBoundary>
-  );
-}
-```
-
-### With Automatic Retry
-
-```tsx
-function AutoRetryBoundary() {
-  const [retryCount, setRetryCount] = useState(0);
-  const maxRetries = 3;
-
-  const handleError = (error: Error) => {
-    if (retryCount < maxRetries) {
-      setTimeout(() => {
-        setRetryCount(prev => prev + 1);
-      }, 1000);
-    } else {
-      Alert.alert('Error', 'Failed after multiple retries');
-    }
-  };
-
-  return (
-    <SettingsErrorBoundary
-      onError={handleError}
-      key={retryCount} // Force remount on retry
-    >
-      <SettingsScreen />
-    </SettingsErrorBoundary>
-  );
-}
-```
-
-### Conditional Error Boundary
-
-```tsx
-function ConditionalBoundary({ enabled, children }) {
-  if (!enabled) {
-    return <>{children}</>;
-  }
-
-  return (
-    <SettingsErrorBoundary>
-      {children}
-    </SettingsErrorBoundary>
-  );
-}
-
-// Usage
-<ConditionalBoundary enabled={__DEV__}>
-  <SettingsScreen />
-</ConditionalBoundary>
-```
-
-## Error States
-
-### Loading State Error
-
-```tsx
-function LoadingBoundary() {
-  return (
-    <SettingsErrorBoundary
-      fallback={({ resetError }) => (
-        <View style={styles.container}>
-          <Text>Failed to load settings</Text>
-          <Button
-            title="Retry"
-            onPress={resetError}
-          />
-        </View>
-      )}
-    >
-      <SettingsScreen />
-    </SettingsErrorBoundary>
-  );
-}
-```
-
-### Mutation Error
-
-```tsx
-function MutationBoundary() {
-  return (
-    <SettingsErrorBoundary
-      fallback={({ error, resetError }) => (
-        <View style={styles.container}>
-          <Text>Failed to update settings</Text>
-          <Text>{error.message}</Text>
-          <Button
-            title="Cancel"
-            onPress={() => navigation.goBack()}
-          />
-          <Button
-            title="Retry"
-            onPress={resetError}
-          />
-        </View>
-      )}
-    >
-      <SettingsForm />
-    </SettingsErrorBoundary>
-  );
-}
-```
-
-### Navigation Error
-
-```tsx
-function NavigationBoundary() {
-  return (
-    <SettingsErrorBoundary
-      fallback={({ error }) => (
-        <View style={styles.container}>
-          <Text>Navigation error occurred</Text>
-          <Button
-            title="Go Back"
-            onPress={() => navigation.goBack()}
-          />
-          <Button
-            title="Home"
-            onPress={() => navigation.navigate('Home')}
-          />
-        </View>
-      )}
-    >
-      <SettingsNavigator />
-    </SettingsErrorBoundary>
-  );
-}
-```
-
-## Styling
-
-### Custom Styles
-
-```tsx
-function StyledFallback({ error, resetError }) {
-  return (
-    <View style={styles.container}>
-      <LinearGradient
-        colors={['#667eea', '#764ba2']}
-        style={styles.gradient}
-      >
-        <View style={styles.content}>
-          <Ionicons
-            name="warning-outline"
-            size={80}
-            color="white"
-            style={styles.icon}
-          />
-
-          <Text style={styles.title}>Oops!</Text>
-
-          <Text style={styles.message}>
-            Something went wrong
-          </Text>
-
-          {__DEV__ && (
-            <View style={styles.details}>
-              <Text style={styles.errorText}>
-                {error.message}
-              </Text>
-            </View>
-          )}
-
-          <TouchableOpacity
-            style={styles.button}
-            onPress={resetError}
-          >
-            <Text style={styles.buttonText}>Try Again</Text>
-          </TouchableOpacity>
-        </View>
-      </LinearGradient>
-    </View>
-  );
-}
-
-const styles = StyleSheet.create({
-  container: { flex: 1 },
-  gradient: { flex: 1 },
-  content: {
-    flex: 1,
-    justifyContent: 'center',
-    alignItems: 'center',
-    padding: 20,
-  },
-  icon: { marginBottom: 20 },
-  title: {
-    fontSize: 32,
-    fontWeight: 'bold',
-    color: 'white',
-    marginBottom: 10,
-  },
-  message: {
-    fontSize: 16,
-    color: 'white',
-    textAlign: 'center',
-    marginBottom: 20,
-  },
-  details: {
-    backgroundColor: 'rgba(0,0,0,0.2)',
-    padding: 10,
-    borderRadius: 8,
-    marginBottom: 20,
-  },
-  errorText: {
-    color: 'white',
-    fontSize: 12,
-    fontFamily: 'monospace',
-  },
-  button: {
-    backgroundColor: 'white',
-    paddingHorizontal: 30,
-    paddingVertical: 15,
-    borderRadius: 25,
-  },
-  buttonText: {
-    color: '#667eea',
-    fontWeight: 'bold',
-  },
-});
-```
-
-## Best Practices
-
-1. **Wrap Strategically**: Place boundaries at strategic locations
-2. **Custom Fallbacks**: Provide context-specific fallbacks
-3. **Error Reporting**: Integrate with error tracking services
-4. **Recovery Actions**: Offer retry or reset options
-5. **Development Details**: Show details only in development
-6. **User-Friendly**: Use clear, non-technical error messages
-7. **Logging**: Always log errors for debugging
-
-## Related
-
-- **SettingsScreen**: Main screen component
-- **SettingsContent**: Content component
-- **React Error Boundaries**: Official React documentation
-
-## License
-
-MIT
+Related components:
+- **SettingsScreen**: Main screen component that uses error boundaries
+- **SettingsContent**: Content component wrapped by error boundaries
+- **React Error Boundaries**: Official React documentation for error boundaries