@umituz/react-native-auth 3.4.32 → 3.4.34

package/src/presentation/hooks/useProfileUpdate.md

@@ -6,322 +6,294 @@ Hooks for profile update operations and profile editing form management.
 
 ## useProfileUpdate
 
-Hook for profile update operations. Implementation should be provided by the app using Firebase SDK or backend API.
+Hook for updating user profile information (display name, photo URL).
 
-### Usage
+### Strategy
 
+**Purpose**: Provides functionality to update user profile data in Firebase Auth and Firestore. Implementation provided by app using Firebase SDK.
+
+**When to Use**:
+- User profile editing screens
+- Settings screens with profile updates
+- Need to update display name or photo
+- Profile modification operations
+
+**Import Path**:
 ```typescript
 import { useProfileUpdate } from '@umituz/react-native-auth';
+```
 
-function ProfileSettings() {
-  const { updateProfile, isUpdating, error } = useProfileUpdate();
+**Hook Location**: `src/presentation/hooks/useProfileUpdate.ts`
+
+### Rules
+
+**MUST**:
+- Validate user is authenticated before updating
+- Validate input data before calling update
+- Handle loading state during update
+- Display error messages on failure
+- Update both Firebase Auth and Firestore
+- Handle anonymous users appropriately
+
+**MUST NOT**:
+- Allow anonymous users to update profile
+- Update profile without validation
+- Expose sensitive error details
+- Allow partial updates (all-or-nothing)
+
+### Constraints
+
+**PARAMETERS**:
+- `displayName?: string` - New display name
+- `photoURL?: string` - New profile photo URL
+
+**OPERATION RULES**:
+- Updates Firebase Auth user profile
+- Updates Firestore user document
+- Transactional (both or none)
+- Auto-updates auth state
+- Triggers profile listeners
+
+**LIMITATIONS**:
+- Cannot update email (use separate method)
+- Cannot update password (use separate method)
+- Anonymous users cannot update
+- Requires authentication
+
+**ERROR HANDLING**:
+- Validation errors before API call
+- Network errors during update
+- Permission errors (user not authenticated)
+- Firebase errors
 
-  const handleUpdate = async (data: UpdateProfileParams) => {
-    try {
-      await updateProfile(data);
-    } catch (err) {
-      console.error(err);
-    }
-  };
+---
 
-  return <ProfileForm onSave={handleUpdate} />;
-}
-```
+## useProfileEdit
 
-### API
+Hook for managing profile editing form state and validation.
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `updateProfile` | `(params: UpdateProfileParams) => Promise<void>` | Profile update function |
-| `isUpdating` | `boolean` | Update in progress |
-| `error` | `string \| null` | Error message |
+### Strategy
 
-### Create Your Own Implementation
+**Purpose**: Provides form state management for profile editing with validation and change tracking.
 
+**When to Use**:
+- Profile editing forms
+- Settings screens with profile edits
+- Need form validation for profile data
+- Want to track form modifications
+
+**Import Path**:
 ```typescript
-function useProfileUpdate() {
-  const { user } = useAuth();
-  const [isUpdating, setIsUpdating] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-
-  const updateProfile = async (params: UpdateProfileParams) => {
-    if (!user) {
-      throw new Error("No user logged in");
-    }
-
-    if (user.isAnonymous) {
-      throw new Error("Anonymous users cannot update profile");
-    }
-
-    setIsUpdating(true);
-    setError(null);
-
-    try {
-      // Update profile in Firebase Auth
-      await updateProfile(user, {
-        displayName: params.displayName,
-        photoURL: params.photoURL,
-      });
-
-      // Update user document in Firestore
-      await updateDoc(doc(db, 'users', user.uid), {
-        displayName: params.displayName,
-        photoURL: params.photoURL,
-        updatedAt: serverTimestamp(),
-      });
-    } catch (err) {
-      const message = err instanceof Error ? err.message : 'Update failed';
-      setError(message);
-      throw err;
-    } finally {
-      setIsUpdating(false);
-    }
-  };
-
-  return { updateProfile, isUpdating, error };
-}
+import { useProfileEdit } from '@umituz/react-native-auth';
 ```
 
+**Hook Location**: `src/presentation/hooks/useProfileUpdate.ts`
+
+### Rules
+
+**MUST**:
+- Validate form before submission
+- Show validation errors to user
+- Track form modifications
+- Handle email field as read-only
+- Provide clear error messages
+- Reset form after successful submission
+
+**MUST NOT**:
+- Allow invalid form submission
+- Allow email modification (read-only)
+- Submit unchanged data
+- Clear form without confirmation if modified
+
+### Constraints
+
+**FORM FIELDS**:
+- `displayName: string` - Editable
+- `email: string` - Read-only
+- `photoURL: string | null` - Editable
+- `isModified: boolean` - Auto-calculated
+
+**VALIDATION RULES**:
+- Display name: Cannot be empty
+- Email: Valid format (if provided)
+- Photo URL: Valid URL format (if provided)
+
+**RETURNED FUNCTIONS**:
+- `setDisplayName: (value: string) => void`
+- `setEmail: (value: string) => void`
+- `setPhotoURL: (value: string | null) => void`
+- `resetForm: (initial: Partial<ProfileEditFormState>) => void`
+- `validateForm: () => { isValid: boolean; errors: string[] }`
+
+**CHANGE TRACKING**:
+- `isModified` automatically calculated
+- Compares current vs initial values
+- Triggers re-calculation on any change
+- Used to enable/disable save button
+
 ---
 
-## useProfileEdit
+## Validation Strategy
 
-Hook for simple profile editing with form state management.
+### Strategy
 
-### Usage
+**Purpose**: Ensure profile data meets requirements before submission.
 
-```typescript
-import { useProfileEdit } from '@umituz/react-native-auth';
+**Rules**:
+- MUST validate all fields before submission
+- MUST show clear error messages
+- MUST prevent invalid submissions
+- MUST provide real-time validation feedback
 
-function EditProfileScreen({ navigation }) {
-  const {
-    formState,
-    setDisplayName,
-    setEmail,
-    setPhotoURL,
-    resetForm,
-    validateForm,
-  } = useProfileEdit({
-    displayName: user?.displayName || '',
-    email: user?.email || '',
-    photoURL: user?.photoURL || null,
-  });
-
-  const handleSave = () => {
-    const { isValid, errors } = validateForm();
-
-    if (!isValid) {
-      Alert.alert('Error', errors.join('\n'));
-      return;
-    }
-
-    updateProfile({
-      displayName: formState.displayName,
-      photoURL: formState.photoURL,
-    });
-
-    navigation.goBack();
-  };
-
-  return (
-    <ScrollView>
-      <TextInput
-        value={formState.displayName}
-        onChangeText={setDisplayName}
-        placeholder="Full Name"
-      />
-
-      <TextInput
-        value={formState.email}
-        onChangeText={setEmail}
-        placeholder="Email"
-        editable={false}
-      />
-
-      <AvatarUploader
-        photoURL={formState.photoURL}
-        onImageSelected={setPhotoURL}
-      />
-
-      <View style={styles.buttons}>
-        <Button onPress={navigation.goBack}>Cancel</Button>
-        <Button
-          onPress={handleSave}
-          disabled={!formState.isModified}
-        >
-          Save
-        </Button>
-      </View>
-    </ScrollView>
-  );
-}
-```
+**MUST NOT**:
+- Allow empty display names
+- Accept invalid email formats
+- Submit with validation errors
+- Hide validation errors
 
-### API
+### Constraints
 
-#### Return Value
+**DISPLAY NAME VALIDATION**:
+- Required field
+- Minimum length: 1 character
+- Maximum length: 100 characters
+- No special character restrictions
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `formState` | `ProfileEditFormState` | Form state |
-| `setDisplayName` | `(value: string) => void` | Set display name |
-| `setEmail` | `(value: string) => void` | Set email |
-| `setPhotoURL` | `(value: string \| null) => void` | Set photo URL |
-| `resetForm` | `(initial: Partial<ProfileEditFormState>) => void` | Reset form |
-| `validateForm` | `() => { isValid: boolean; errors: string[] }` | Validate form |
+**EMAIL VALIDATION**:
+- Valid email format required
+- Read-only field (cannot change)
+- Must match Firebase user email
+- Used for display only
 
-#### ProfileEditFormState
+**PHOTO URL VALIDATION**:
+- Optional field
+- Must be valid URL if provided
+- Supports HTTP, HTTPS URLs
+- Can be cleared (set to null)
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `displayName` | `string` | Display name |
-| `email` | `string` | Email |
-| `photoURL` | `string \| null` | Photo URL |
-| `isModified` | `boolean` | Form has been modified |
+**VALIDATION TIMING**:
+- Real-time validation on input
+- Final validation on submit
+- Clear errors on correction
+- Error messages localized
 
-### Validation
+---
 
-`validateForm()` checks:
+## Anonymous User Handling
 
-- **Display name**: Cannot be empty
-- **Email**: Valid email format (if provided)
+### Strategy
 
-```typescript
-const { isValid, errors } = validateForm();
+**Purpose**: Prevent profile updates from anonymous users.
 
-if (!isValid) {
-  errors.forEach(error => console.log(error));
-  // ["Display name is required", "Invalid email format"]
-}
-```
+**Rules**:
+- MUST check user is not anonymous
+- MUST hide profile edit for anonymous users
+- MUST show upgrade prompt instead
+- MUST NOT allow anonymous profile updates
 
-## Examples
+**Constraints**:
+- Anonymous users cannot update profile
+- Show "Create account" prompt
+- Guide to registration
+- Preserve anonymous data during upgrade
 
-### Profile Photo Upload
+---
 
-```typescript
-function ProfilePhotoSection() {
-  const { formState, setPhotoURL } = useProfileEdit(initialState);
-
-  const handlePickImage = async () => {
-    const result = await launchImageLibrary({
-      mediaType: 'photo',
-      quality: 0.8,
-    });
-
-    if (result.assets?.[0]) {
-      // Upload to storage and get URL
-      const url = await uploadToStorage(result.assets[0].uri);
-      setPhotoURL(url);
-    }
-  };
-
-  return (
-    <TouchableOpacity onPress={handlePickImage}>
-      {formState.photoURL ? (
-        <Image source={{ uri: formState.photoURL }} />
-      ) : (
-        <View style={styles.placeholder}>
-          <Text>Select Photo</Text>
-        </View>
-      )}
-    </TouchableOpacity>
-  );
-}
-```
+## Error Handling
 
-### Unsaved Changes Warning
+### Strategy
 
-```typescript
-function EditProfileScreen({ navigation }) {
-  const {
-    formState,
-    resetForm,
-    validateForm
-  } = useProfileEdit(initialState);
-
-  useEffect(() => {
-    const unsubscribe = navigation.addListener('beforeRemove', (e) => {
-      if (!formState.isModified) {
-        return;
-      }
-
-      e.preventDefault();
-
-      Alert.alert(
-        'Unsaved Changes',
-        'You have unsaved changes. What would you like to do?',
-        [
-          { text: 'Don\'t Save', style: 'cancel' },
-          {
-            text: 'Save',
-            onPress: () => {
-              saveChanges();
-              navigation.dispatch(e.data.action);
-            }
-          },
-          {
-            text: 'Discard',
-            style: 'destructive',
-            onPress: () => {
-              resetForm(initialState);
-              navigation.dispatch(e.data.action);
-            }
-          },
-        ]
-      );
-    });
-
-    return unsubscribe;
-  }, [navigation, formState.isModified]);
-
-  // ...
-}
-```
+**Purpose**: Graceful handling of profile update failures.
 
-### Custom Validation
+**Rules**:
+- MUST catch all errors during update
+- MUST show user-friendly error messages
+- MUST allow retry after failures
+- MUST not lose form data on error
 
-```typescript
-function ExtendedProfileEdit() {
-  const {
-    formState,
-    setDisplayName,
-    setEmail,
-    setPhotoURL,
-    validateForm
-  } = useProfileEdit(initialState);
-
-  const handleSave = () => {
-    // Base validation
-    const { isValid, errors } = validateForm();
-
-    // Custom validation
-    const customErrors = [];
-
-    if (formState.displayName.length < 3) {
-      customErrors.push('Display name must be at least 3 characters');
-    }
-
-    if (formState.photoURL && !isValidImageUrl(formState.photoURL)) {
-      customErrors.push('Invalid image URL');
-    }
-
-    const allErrors = [...errors, ...customErrors];
-
-    if (allErrors.length > 0) {
-      Alert.alert('Error', allErrors.join('\n'));
-      return;
-    }
-
-    saveProfile();
-  };
-
-  // ...
-}
-```
+**MUST NOT**:
+- Show raw error messages
+- Crash on update failures
+- Lose user input on errors
+- Block retry attempts
+
+### Constraints
+
+**ERROR TYPES**:
+- Validation errors: Before API call
+- Network errors: During update
+- Permission errors: Not authenticated
+- Firebase errors: From service
+
+**ERROR RECOVERY**:
+- Keep form data on error
+- Allow user to retry
+- Clear errors on new input
+- Show retry button
+
+---
+
+## Performance Optimization
+
+### Strategy
+
+**Purpose**: Efficient form state management and updates.
+
+**Rules**:
+- MUST minimize unnecessary re-renders
+- MUST debounce validation if expensive
+- MUST optimize form state updates
+- MUST prevent excessive recalculations
+
+**Constraints**:
+- Form state in local component
+- Efficient validation checks
+- Minimal prop drilling
+- Optimized re-render triggers
+
+---
+
+## Security Considerations
+
+### Strategy
+
+**Purpose**: Secure profile data updates.
+
+**Rules**:
+- MUST validate user owns profile
+- MUST sanitize input data
+- MUST use secure upload for photos
+- MUST not expose sensitive data
+
+**MUST NOT**:
+- Allow cross-user profile updates
+- Accept unvalidated photo URLs
+- Expose user IDs in errors
+- Log profile data with sensitive info
+
+### Constraints
+
+**PERMISSION CHECKS**:
+- User can only update own profile
+- Firebase security rules enforce
+- Server-side validation required
+- Token-based authentication
+
+**DATA SANITIZATION**:
+- Trim whitespace from names
+- Validate URL formats
+- Escape special characters
+- Prevent XSS attacks
+
+---
 
 ## Related Hooks
 
-- [`useUserProfile`](./useUserProfile.md) - Display profile data
-- [`useAuth`](./useAuth.md) - Main auth state management
-- [`useAccountManagement`](./useAccountManagement.md) - Account operations
+- **`useAuth`** (`src/presentation/hooks/useAuth.ts`) - Authentication state
+- **`useUserProfile`** (`src/presentation/hooks/useUserProfile.ts`) - Profile display data
+- **`useAccountManagement`** (`src/presentation/hooks/useAccountManagement.md`) - Account operations
+
+## Related Components
+
+- **`ProfileSection`** (`src/presentation/components/ProfileComponents.md`) - Profile display
+- **`EditProfileForm`** (`src/presentation/components/ProfileComponents.md`) - Profile editing UI