@umituz/react-native-settings 4.20.58 → 4.20.59

package/src/presentation/screens/components/SettingsHeader/README.md

@@ -1,322 +1,67 @@
 # Settings Header
 
-Header component for the settings screen with optional close button functionality.
+## Purpose
 
-## Features
+Header component for the settings screen with optional close button functionality for modal/presentation styles.
 
-- **Screen Title**: Displays localized "Settings" title
-- **Close Button**: Optional close button for modal/presentation
-- **Auto Navigation**: Automatically goes back if no custom handler
-- **Design System**: Uses design system tokens for styling
-- **Internationalization**: Supports i18n
+## File Paths
 
-## Installation
+- **Component**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/components/SettingsHeader/SettingsHeader.tsx`
 
-This component is part of `@umituz/react-native-settings`.
+## Strategy
 
-## Usage
+1. **Screen Title**: Displays localized "Settings" title using translation system
+2. **Close Button**: Optional close button for modal presentation style
+3. **Auto Navigation**: Automatically goes back if no custom handler is provided
+4. **Design System**: Uses design system tokens for consistent styling
+5. **Internationalization**: Supports i18n for all text content
 
-### Basic Header
+## Restrictions (Forbidden)
 
-```tsx
-import { SettingsHeader } from '@umituz/react-native-settings';
+### DO NOT
+- ❌ DO NOT use SettingsHeader in non-modal presentations (let React Navigation handle header)
+- ❌ DO NOT override the title text (use translation system)
+- ❌ DO NOT add custom actions to the header
 
-function MySettingsScreen() {
-  return (
-    <>
-      <SettingsHeader />
-      {/* Rest of screen content */}
-    </>
-  );
-}
-```
+### NEVER
+- ❌ NEVER use SettingsHeader with card-style stack navigation
+- ❌ NEVER remove or hide the close button in modal presentation
+- ❌ NEVER hardcode title text (must use translations)
 
-### With Close Button
+### AVOID
+- ❌ AVOID adding additional buttons or actions to the header
+- ❌ AVOID custom styling that breaks design system consistency
+- ❌ AVOID using SettingsHeader outside of modal presentation context
 
-```tsx
-function ModalSettingsScreen() {
-  const handleClose = () => {
-    navigation.goBack();
-  };
+## Rules (Mandatory)
 
-  return (
-    <>
-      <SettingsHeader
-        showCloseButton={true}
-        onClose={handleClose}
-      />
-      {/* Settings content */}
-    </>
-  );
-}
-```
+### ALWAYS
+- ✅ ALWAYS use close button in modal presentation (`presentation: 'modal'`)
+- ✅ ALWAYS provide custom close handler when needed
+- ✅ ALWAYS use translation keys for all text
+- ✅ MUST set `headerShown: false` in screen options when using SettingsHeader
 
-## Props
+### MUST
+- ✅ MUST ensure close button is easily tappable (44x44 minimum)
+- ✅ MUST provide confirmation if there are unsaved changes
+- ✅ MUST use proper navigation.goBack() as default close behavior
 
-### SettingsHeaderProps
+### SHOULD
+- ✅ SHOULD use custom close handler for special actions (e.g., save before close)
+- ✅ SHOULD test close button in both iOS and Android
+- ✅ SHOULD ensure proper hit area for close button (hitSlop)
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `showCloseButton` | `boolean` | `false` | Show close button |
-| `onClose` | `() => void` | `undefined` | Custom close handler |
+## AI Agent Guidelines
 
-## Behavior
+1. **File Reference**: When modifying header behavior, refer to `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/screens/components/SettingsHeader/SettingsHeader.tsx`
+2. **Modal Setup**: Always set `presentation: 'modal'` and `headerShown: false` in screen options
+3. **Close Handler**: If custom close logic is needed (save, confirm), provide via `onClose` prop
+4. **Navigation**: Default behavior calls `navigation.goBack()` when no `onClose` is provided
+5. **Accessibility**: Ensure close button has proper accessibility label
 
-### Close Button
+## Component Reference
 
-When `showCloseButton` is `true`:
-
-- If `onClose` provided: Calls `onClose()`
-- If no `onClose`: Calls `navigation.goBack()`
-
-### Close Handler
-
-```typescript
-const handleClose = () => {
-  if (onClose) {
-    onClose();  // Use custom handler
-  } else {
-    navigation.goBack();  // Default navigation
-  }
-};
-```
-
-## Examples
-
-### Modal Settings
-
-```tsx
-import { SettingsHeader } from '@umituz/react-native-settings';
-import { Modal } from 'react-native';
-
-function SettingsModal({ visible, onClose }) {
-  return (
-    <Modal visible={visible} animationType="slide">
-      <SettingsHeader
-        showCloseButton={true}
-        onClose={onClose}
-      />
-      <SettingsContent />
-    </Modal>
-  );
-}
-```
-
-### Presentation Style
-
-```tsx
-import { SettingsHeader } from '@umituz/react-native-settings';
-
-function PresentationSettings() {
-  const navigation = useNavigation();
-
-  return (
-    <Stack.Screen
-      name="Settings"
-      options={{
-        presentation: 'modal',
-        headerShown: false,
-      }}
-    >
-      {() => (
-        <View>
-          <SettingsHeader
-            showCloseButton={true}
-            onClose={() => navigation.goBack()}
-          />
-          <SettingsContent />
-        </View>
-      )}
-    </Stack.Screen>
-  );
-}
-```
-
-### Custom Close Action
-
-```tsx
-function SettingsWithCustomClose() {
-  const handleClose = () => {
-    // Custom logic before closing
-    saveDraftChanges();
-    navigation.goBack();
-  };
-
-  return (
-    <SettingsHeader
-      showCloseButton={true}
-      onClose={handleClose}
-    />
-  );
-}
-```
-
-### Close with Confirmation
-
-```tsx
-function SettingsWithConfirmation() {
-  const handleClose = () => {
-    Alert.alert(
-      'Discard Changes?',
-      'You have unsaved changes',
-      [
-        { text: 'Keep Editing', style: 'cancel' },
-        {
-          text: 'Discard',
-          style: 'destructive',
-          onPress: () => navigation.goBack(),
-        },
-      ]
-    );
-  };
-
-  return (
-    <SettingsHeader
-      showCloseButton={true}
-      onClose={handleClose}
-    />
-  );
-}
-```
-
-## Styling
-
-### Layout
-
-```typescript
-const styles = StyleSheet.create({
-  container: {
-    flexDirection: 'row',
-    justifyContent: 'space-between',
-    alignItems: 'center',
-    padding: tokens.spacing.lg,  // 16px
-  },
-  closeButton: {
-    width: 44,
-    height: 44,
-    justifyContent: 'center',
-    alignItems: 'center',
-  },
-});
-```
-
-### Pressable Style
-
-The close button uses Pressable with pressed state:
-
-```typescript
-style={({ pressed }) => [
-  styles.closeButton,
-  {
-    backgroundColor: pressed
-      ? tokens.colors.surfaceVariant
-      : tokens.colors.surface,
-    borderRadius: tokens.borderRadius.full,
-  },
-]
-```
-
-## Internationalization
-
-Uses translation key for title:
-
-```typescript
-t('settings.title')
-```
-
-## Design System Integration
-
-- **Typography**: `tokens.typography.headingLarge` for title
-- **Colors**: `tokens.colors.textPrimary` for close icon
-- **Spacing**: `tokens.spacing.lg` for padding
-- **Border Radius**: `tokens.borderRadius.full` for button
-- **Icons**: `AtomicIcon` from design system
-
-## Accessibility
-
-### Hit Slop
-
-Close button has increased hit area:
-
-```typescript
-hitSlop={{ top: 10, bottom: 10, left: 10, right: 10 }}
-```
-
-### Icon
-
-Uses `close-outline` icon from Ionicons:
-
-```typescript
-<AtomicIcon name="close-outline" size="lg" color="textPrimary" />
-```
-
-## Best Practices
-
-1. **Modal Screens**: Always use close button in modal presentation
-2. **Custom Handler**: Provide custom close handler when needed
-3. **Confirmation**: Ask for confirmation if there are unsaved changes
-4. **Consistent Position**: Keep header at top of screen
-5. **Padding**: Use design system spacing for consistency
-6. **Accessibility**: Ensure close button is easily tappable
-
-## Use Cases
-
-### Modal Presentation
-
-```tsx
-<Stack.Screen
-  name="Settings"
-  options={{
-    presentation: 'modal',
-    headerShown: false,
-  }}
->
-  {() => (
-    <View>
-      <SettingsHeader showCloseButton={true} />
-      <SettingsContent />
-    </View>
-  )}
-</Stack.Screen>
-```
-
-### Full Screen with Close
-
-```tsx
-function FullScreenSettings() {
-  return (
-    <ScreenLayout
-      header={<SettingsHeader showCloseButton={true} />}
-    >
-      <SettingsContent />
-    </ScreenLayout>
-  );
-}
-```
-
-### No Close Button (Default)
-
-```tsx
-function RegularSettingsScreen() {
-  return (
-    <Stack.Screen name="Settings">
-      {() => (
-        <View>
-          <SettingsHeader />
-          <SettingsContent />
-        </View>
-      )}
-    </Stack.Screen>
-  );
-}
-```
-
-## Related
-
-- **SettingsScreen**: Main screen component
-- **SettingsContent**: Content component
-- **Design System**: Styling and theming
-
-## License
-
-MIT
+Related components:
+- **SettingsScreen**: Main screen component that uses SettingsHeader
+- **SettingsContent**: Content component that appears below header
+- **Design System**: Styling and theming tokens