@umituz/react-native-settings 4.20.58 → 4.20.60

package/src/presentation/components/SettingsItemCard/STRATEGY.md

@@ -0,0 +1,164 @@
+# SettingsItemCard
+
+## Purpose
+Premium, consistent card component for displaying settings items with icons, text, and optional controls (switches, chevrons).
+
+## File Path
+`src/presentation/components/SettingsItemCard/SettingsItemCard.tsx`
+
+## Imports
+```typescript
+import { SettingsItemCard } from '@umituz/react-native-settings';
+```
+
+## Strategy
+
+### When to Use
+- Use for ALL settings list items
+- Use when displaying navigation items
+- Use for toggle/switch settings
+- Use for any setting that requires user interaction
+
+### Integration Pattern
+1. Import from `@umituz/react-native-settings`
+2. Reference the implementation file for current props
+3. Check `SettingsItemCardProps` interface for available options
+4. Use design system tokens for custom styling
+
+### Best Practices
+- Keep titles short and descriptive
+- Use descriptions for additional context
+- Provide press handlers for navigation
+- Use switches for boolean toggles
+- Show right icons for navigation hints
+
+## Restrictions (Forbidden)
+
+### ❌ DO NOT
+- Create custom settings item components
+- Inline settings item logic in screens
+- Use TouchableOpacity directly for settings items
+- Mix different settings item styles
+- Hardcode colors or sizes
+
+### ❌ NEVER
+- Bypass SettingsItemCard for settings items
+- Use different icon libraries
+- Override internal styles directly
+- Nest SettingsItemCard deeply
+
+### ❌ AVOID
+- Overloading with too many props
+- Using without proper accessibility
+- Creating variants outside the component
+- Duplicating functionality
+
+## Rules
+
+### ✅ ALWAYS
+- Use SettingsItemCard for all settings items
+- Import from `@umituz/react-native-settings`
+- Provide required props: `icon`, `title`
+- Add `onPress` handler for interactive items
+- Use proper icon names from Ionicons
+- Include accessibility labels
+
+### ✅ MUST
+- Follow SettingsItemCardProps interface
+- Use design system tokens for styling
+- Handle press events appropriately
+- Provide meaningful titles
+- Support both light and dark themes
+
+### ✅ SHOULD
+- Use description/subtitle for context
+- Show switches for boolean settings
+- Display right icons for navigation
+- Group related items in sections
+- Test on both iOS and Android
+
+## Props Reference
+
+See implementation file for complete props:
+`src/presentation/components/SettingsItemCard/SettingsItemCard.tsx`
+
+Required props:
+- `icon`: IconName from Ionicons
+- `title`: string
+
+Common optional props:
+- `subtitle`/`description`: Additional text
+- `onPress`: Press handler
+- `showSwitch`: Boolean for toggle
+- `switchValue`: Switch state
+- `onSwitchChange`: Switch change handler
+- `rightIcon`: Right-side icon
+- `disabled`: Disable interaction
+
+## Related Components
+
+- **SettingsSection**: `src/presentation/screens/components/sections/SettingsSection/SettingsSection.tsx`
+  - Container for grouping SettingsItemCard components
+
+- **SettingsContent**: `src/presentation/screens/components/SettingsContent/SettingsContent.tsx`
+  - Main content composer that uses SettingsItemCard
+
+- **SettingsScreen**: `src/presentation/screens/SettingsScreen.tsx`
+  - Main screen that displays settings items
+
+## AI Agent Guidelines
+
+### When Generating SettingsItemCard Code
+
+1. **Import Statement**
+   ```typescript
+   import { SettingsItemCard } from '@umituz/react-native-settings';
+   ```
+
+2. **Required Props**
+   - Always provide `icon` (Ionicons name)
+   - Always provide `title` (string)
+
+3. **Common Patterns**
+   - Navigation items: Add `onPress` and `rightIcon`
+   - Toggle items: Add `showSwitch`, `switchValue`, `onSwitchChange`
+   - Disabled items: Add `disabled={true}`
+
+4. **What to Avoid**
+   - Don't create custom card components
+   - Don't wrap in unnecessary containers
+   - Don't hardcode colors
+   - Don't use inline styles
+
+5. **File Reference**
+   - Check implementation: `src/presentation/components/SettingsItemCard/SettingsItemCard.tsx`
+   - Check props interface: `SettingsItemCardProps`
+   - Check styles: Look for design system tokens usage
+
+6. **Consistency Rules**
+   - Use same icon style across app
+   - Keep titles concise (1-3 words)
+   - Use descriptions only when needed
+   - Group related items together
+
+### Example Pattern (Conceptual)
+
+Instead of code examples, follow this pattern:
+
+```
+Settings Item → SettingsItemCard
+  - Required: icon, title
+  - Navigation: onPress, rightIcon
+  - Toggle: showSwitch, switchValue, onSwitchChange
+  - Disabled: disabled={true}
+```
+
+## Version Compatibility
+
+- Minimum React Native version: 0.60.0
+- Requires: @umituz/react-native-design-system
+- Compatible with: React Navigation 6.x
+
+## License
+
+MIT

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

@@ -1,421 +1,67 @@
 # SettingsSection
 
-Container component for grouping related settings items with section headers and consistent styling.
-
-## Features
-
-- **Grouping**: Groups related settings together
-- **Headers**: Optional section titles with styling
-- **Spacing**: Consistent spacing between sections
-- **Customizable**: Custom styles and headers
-- **Flexible**: Supports any content as children
-
-## Installation
-
-This component is part of `@umituz/react-native-settings`.
-
-## Usage
-
-### Basic Section
-
-```tsx
-import { SettingsSection } from '@umituz/react-native-settings';
-
-function GeneralSettings() {
-  return (
-    <SettingsSection title="GENERAL">
-      <SettingsItemCard
-        icon="person-outline"
-        title="Profile"
-        rightIcon="chevron-forward"
-        onPress={() => {}}
-      />
-      <SettingsItemCard
-        icon="notifications-outline"
-        title="Notifications"
-        showSwitch={true}
-        switchValue={enabled}
-        onSwitchChange={setEnabled}
-      />
-    </SettingsSection>
-  );
-}
-```
-
-### Without Title
-
-```tsx
-function UntitledSection() {
-  return (
-    <SettingsSection>
-      <SettingsItemCard
-        icon="settings-outline"
-        title="Settings"
-        onPress={() => {}}
-      />
-    </SettingsSection>
-  );
-}
-```
-
-### With Custom Style
-
-```tsx
-function StyledSection() {
-  return (
-    <SettingsSection
-      title="APPEARANCE"
-      style={{ backgroundColor: '#f5f5f5' }}
-      titleStyle={{ color: '#2196F3' }}
-    >
-      <SettingsItemCard
-        icon="moon-outline"
-        title="Dark Mode"
-        showSwitch={true}
-        switchValue={darkMode}
-        onSwitchChange={setDarkMode}
-      />
-    </SettingsSection>
-  );
-}
-```
-
-## Props
-
-### SettingsSectionProps
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `title` | `string` | `undefined` | Section title |
-| `children` | `ReactNode` | **Required** | Section content |
-| `style` | `ViewStyle` | `undefined` | Custom container style |
-| `titleStyle` | `TextStyle` | `undefined` | Custom title style |
-| `showTitle` | `boolean` | `true` | Show/hide title |
-| `containerStyle` | `ViewStyle` | `undefined` | Content container style |
-| `testID` | `string` | `undefined` | Test identifier |
-
-## Component Structure
-
-```
-SettingsSection
-├── Section Header (if title provided)
-│   └── Title Text
-└── Content Container
-    └── Children (SettingsItemCard components)
-```
-
-## Examples
-
-### Multiple Sections
-
-```tsx
-function SettingsScreen() {
-  return (
-    <ScrollView>
-      <SettingsSection title="GENERAL">
-        <SettingsItemCard icon="person-outline" title="Profile" onPress={() => {}} />
-        <SettingsItemCard icon="notifications-outline" title="Notifications" onPress={() => {}} />
-      </SettingsSection>
-
-      <SettingsSection title="APPEARANCE">
-        <SettingsItemCard icon="moon-outline" title="Dark Mode" onPress={() => {}} />
-        <SettingsItemCard icon="color-palette-outline" title="Theme" onPress={() => {}} />
-      </SettingsSection>
-
-      <SettingsSection title="PRIVACY">
-        <SettingsItemCard icon="shield-outline" title="Privacy" onPress={() => {}} />
-        <SettingsItemCard icon="lock-closed-outline" title="Security" onPress={() => {}} />
-      </SettingsSection>
-    </ScrollView>
-  );
-}
-```
-
-### With Header Customization
-
-```tsx
-function CustomHeaderSection() {
-  return (
-    <SettingsSection
-      title="PREFERENCES"
-      titleStyle={{
-        fontSize: 12,
-        fontWeight: '700',
-        color: '#2196F3',
-        letterSpacing: 1,
-      }}
-    >
-      <SettingsItemCard
-        icon="globe-outline"
-        title="Language"
-        subtitle="English"
-        onPress={() => {}}
-      />
-    </SettingsSection>
-  );
-}
-```
+## Purpose
 
-### With Custom Spacing
-
-```tsx
-function SpacedSection() {
-  return (
-    <SettingsSection
-      title="SETTINGS"
-      style={{ marginBottom: 20 }}
-      containerStyle={{ gap: 10 }}
-    >
-      <SettingsItemCard icon="cog-outline" title="Settings" onPress={() => {}} />
-      <SettingsItemCard icon="apps-outline" title="Apps" onPress={() => {}} />
-    </SettingsSection>
-  );
-}
-```
-
-### Nested Content
-
-```tsx
-function NestedContentSection() {
-  return (
-    <SettingsSection title="ADVANCED">
-      <View>
-        <Text style={styles.heading}>Display Options</Text>
-        <SettingsItemCard
-          icon="eye-outline"
-          title="Show Preview"
-          showSwitch={true}
-          switchValue={showPreview}
-          onSwitchChange={setShowPreview}
-        />
-      </View>
-
-      <View>
-        <Text style={styles.heading}>Storage</Text>
-        <SettingsItemCard
-          icon="trash-outline"
-          title="Clear Cache"
-          onPress={() => {}}
-        />
-      </View>
-    </SettingsSection>
-  );
-}
-```
-
-### Conditional Items
-
-```tsx
-function ConditionalSection() {
-  const isPro = useIsProUser();
-
-  return (
-    <SettingsSection title="PREMIUM">
-      <SettingsItemCard
-        icon="star-outline"
-        title="Upgrade to Pro"
-        subtitle="Get all premium features"
-        onPress={() => {}}
-      />
-
-      {isPro && (
-        <SettingsItemCard
-          icon="diamond-outline"
-          title="Pro Features"
-          subtitle="Manage your subscription"
-          onPress={() => {}}
-        />
-      )}
-
-      {isPro && (
-        <SettingsItemCard
-          icon="card-outline"
-          title="Billing"
-          onPress={() => {}}
-        />
-      )}
-    </SettingsSection>
-  );
-}
-```
-
-## Styling
-
-### Default Styles
-
-```typescript
-const styles = StyleSheet.create({
-  container: {
-    marginTop: tokens.spacing.lg,
-  },
-  title: {
-    fontSize: tokens.typography.fontSize.xs,
-    fontWeight: '700',
-    color: tokens.colors.textSecondary,
-    textTransform: 'uppercase',
-    letterSpacing: 0.5,
-    marginLeft: tokens.spacing.xl,
-    marginBottom: tokens.spacing.sm,
-  },
-  content: {
-    // No additional styling by default
-  },
-});
-```
-
-### Custom Section Styles
-
-```tsx
-<SettingsSection
-  title="CUSTOM"
-  style={{
-    backgroundColor: '#fff',
-    padding: 10,
-    borderRadius: 10,
-    margin: 15,
-  }}
-  titleStyle={{
-    color: '#FF5722',
-    fontSize: 14,
-    fontWeight: 'bold',
-  }}
->
-  {/* Content */}
-</SettingsSection>
-```
-
-### Section Variants
-
-#### Compact Section
-
-```tsx
-<SettingsSection
-  title="QUICK SETTINGS"
-  style={{ marginTop: tokens.spacing.sm }}
->
-  {/* Items */}
-</SettingsSection>
-```
-
-#### Spaced Section
-
-```tsx
-<SettingsSection
-  title="SETTINGS"
-  style={{ marginTop: tokens.spacing.xl }}
->
-  {/* Items */}
-</SettingsSection>
-```
-
-#### Full Width Section
-
-```tsx
-<SettingsSection
-  title="FULL WIDTH"
-  style={{ marginHorizontal: 0 }}
-  titleStyle={{ marginLeft: tokens.spacing.lg }}
->
-  {/* Items */}
-</SettingsSection>
-```
-
-## Layout Integration
+Container component for grouping related settings items with section headers and consistent styling.
 
-### In ScrollView
+## File Paths
 
-```tsx
-function SettingsScreen() {
-  return (
-    <ScrollView style={styles.scrollView}>
-      <SettingsSection title="GENERAL">
-        <SettingsItemCard icon="person-outline" title="Profile" onPress={() => {}} />
-        <SettingsItemCard icon="notifications-outline" title="Notifications" onPress={() => {}} />
-      </SettingsSection>
+- **Component**: `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/components/SettingsSection/SettingsSection.tsx`
 
-      <SettingsSection title="APPEARANCE">
-        <SettingsItemCard icon="moon-outline" title="Dark Mode" onPress={() => {}} />
-      </SettingsSection>
-    </ScrollView>
-  );
-}
-```
+## Strategy
 
-### In FlatList
+1. **Logical Grouping**: Groups related settings together under section headers for better organization and user experience
+2. **Flexible Layout**: Supports any content as children, allowing for dynamic settings items
+3. **Consistent Spacing**: Uses design system tokens to maintain uniform spacing between sections
+4. **Optional Headers**: Section titles are optional, allowing for unlabeled groups when needed
+5. **Customizable Styling**: Supports custom styles for both container and title to match design requirements
 
-```tsx
-function SettingsScreen() {
-  const sections = [
-    {
-      title: 'GENERAL',
-      data: [
-        { id: '1', title: 'Profile', icon: 'person-outline' },
-        { id: '2', title: 'Notifications', icon: 'notifications-outline' },
-      ],
-    },
-    {
-      title: 'APPEARANCE',
-      data: [
-        { id: '3', title: 'Dark Mode', icon: 'moon-outline' },
-      ],
-    },
-  ];
+## Restrictions (Forbidden)
 
-  const renderSectionHeader = ({ section }) => (
-    <SettingsSection title={section.title}>
-      {section.data.map((item) => (
-        <SettingsItemCard
-          key={item.id}
-          icon={item.icon}
-          title={item.title}
-          onPress={() => {}}
-        />
-      ))}
-    </SettingsSection>
-  );
+### DO NOT
+- ❌ DO NOT nest SettingsSection components deeply (maximum 2 levels recommended)
+- ❌ DO NOT mix different types of content unpredictably within sections
+- ❌ DO NOT use hardcoded spacing values instead of design system tokens
 
-  return (
-    <SectionList
-      sections={sections}
-      renderSectionHeader={renderSectionHeader}
-      keyExtractor={(item) => item.id}
-    />
-  );
-}
-```
+### NEVER
+- ❌ NEVER use SettingsSection for non-settings content (e.g., forms, data displays)
+- ❌ NEVER override critical accessibility properties
+- ❌ NEVER use section titles that are misleading or unclear
 
-## Best Practices
+### AVOID
+- ❌ AVOID creating sections with only one item (consider placing in another section)
+- ❌ AVOID using overly long section titles (keep under 25 characters)
+- ❌ AVOID inconsistent section ordering across different screens
 
-1. **Logical Grouping**: Group related settings together
-2. **Clear Titles**: Use descriptive, concise section titles
-3. **Consistent Spacing**: Maintain consistent spacing between sections
-4. **Order**: Order sections by importance or frequency of use
-5. **Limit Items**: Keep sections focused (3-6 items max)
-6. **Accessibility**: Ensure sections are accessible
-7. **Styling**: Use design system tokens for consistency
+## Rules (Mandatory)
 
-## Section Title Guidelines
+### ALWAYS
+- ✅ ALWAYS use design system tokens for spacing and styling
+- ✅ ALWAYS provide clear, concise section titles in uppercase
+- ✅ ALWAYS maintain consistent spacing between sections using tokens
+- ✅ ALWAYS test section appearance in both light and dark themes
 
-### Good Titles
+### MUST
+- ✅ MUST group related settings logically (e.g., all notification settings together)
+- ✅ MUST ensure section titles are descriptive and accurate
+- ✅ MUST keep sections focused (3-6 items maximum recommended)
 
-- ✅ "GENERAL" - Clear and concise
-- ✅ "APPEARANCE" - Descriptive
-- ✅ "NOTIFICATIONS" - Specific
-- ✅ "PRIVACY & SECURITY" - Combined topics
+### SHOULD
+- ✅ SHOULD order sections by importance or frequency of use
+- ✅ SHOULD use section titles that follow the pattern: [CATEGORY] or [FEATURE GROUP]
+- ✅ SHOULD consider internationalization for section titles
 
-### Avoid
+## AI Agent Guidelines
 
-- ❌ "Settings" - Too generic
-- ❌ "Stuff" - Not descriptive
-- ❌ "Misc" - Vague
-- ❌ "Other" - Unclear
+1. **File Reference**: When modifying section layout, refer to `/Users/umituz/Desktop/github/umituz/apps/artificial_intelligence/npm-packages/react-native-settings/src/presentation/components/SettingsSection/SettingsSection.tsx`
+2. **Design Tokens**: All spacing and styling must use tokens from the design system (e.g., `tokens.spacing.lg`, `tokens.colors.textSecondary`)
+3. **Component Integration**: SettingsSection is designed to work with SettingsItemCard components as children
+4. **Accessibility**: Ensure sections are properly labeled for screen readers
+5. **Performance**: Avoid unnecessary re-renders by keeping section configuration stable
 
-## Related
+## Component Reference
 
-- **SettingsItemCard**: Individual item component
-- **SettingsContent**: Content composer
+Related components:
+- **SettingsItemCard**: Individual item component to be used inside sections
+- **SettingsContent**: Content composer that manages multiple sections
 - **SettingsScreen**: Main screen component
-
-## License
-
-MIT