@umituz/react-native-subscription 2.14.99 → 2.14.101

package/src/presentation/README.md

@@ -1,410 +1,125 @@
 # Presentation Layer
 
-Abonelik sisteminin UI/UX katmanı - React hooks, components ve screen'ler.
-
-## Sorumluluklar
-
-- **React Hooks**: State management ve veri erişimi
-- **Components**: UI bileşenleri
-- **Screens**: Tam ekran sayfalar
-- **User Interaction**: Kullanıcı etkileşimlerini yönetme
-
-## Yapı
-
-```
-presentation/
-├── hooks/              # React hooks
-│   ├── usePremium.ts
-│   ├── useSubscription.ts
-│   ├── useCredits.ts
-│   └── ...
-├── components/         # UI bileşenleri
-│   ├── details/       # Detay kartları, badge'ler
-│   ├── feedback/      # Modal, feedback bileşenleri
-│   └── sections/      # Section bileşenleri
-└── screens/           # Ekranlar
-    └── SubscriptionDetailScreen.tsx
-```
-
-## Hooks
-
-Tüm hooks `src/presentation/hooks/` dizininde README.md dosyasında detaylı olarak açıklanmıştır.
-
-Ana hooks:
-- `usePremium` - Premium durumu
-- `useSubscription` - Abonelik durumu
-- `useCredits` - Kredi bakiyesi
-- `usePremiumGate` - Premium özellik kontrolü
-- `useCreditsGate` - Kredi özellik kontrolü
-- `usePaywall*` - Paywall yönetimi
-
-Detaylı bilgi için: [hooks/README.md](./hooks/README.md)
-
-## Components
-
-### Details Components
-
-Detay gösterimi için bileşenler:
-
-```
-components/details/
-├── PremiumDetailsCard.tsx       # Premium detay kartı
-├── PremiumDetailsCard.styles.ts
-├── PremiumDetailsCardTypes.ts
-├── PremiumStatusBadge.tsx       # Durum badge'i
-└── PremiumDetailsCard.styles.ts
-```
-
-**PremiumDetailsCard Kullanımı:**
-
-```typescript
-import { PremiumDetailsCard } from '@umituz/react-native-subscription';
-
-<PremiumDetailsCard
-  status={{
-    type: 'premium',
-    isActive: true,
-    expirationDate: '2025-12-31',
-    willRenew: true,
-  }}
-  onUpgradePress={() => console.log('Upgrade pressed')}
-  onManagePress={() => console.log('Manage pressed')}
-  translations={{
-    title: 'Premium',
-    status: 'Active',
-    expires: 'Expires on',
-    renew: 'Renews on',
-  }}
-/>
-```
-
-**PremiumStatusBadge Kullanımı:**
-
-```typescript
-import { PremiumStatusBadge } from '@umituz/react-native-subscription';
-
-<PremiumStatusBadge
-  status="premium"
-  size="medium"
-  showIcon={true}
-/>
-```
-
-### Feedback Components
-
-Kullanıcı feedback'i için bileşenler:
-
-```
-components/feedback/
-├── PaywallFeedbackModal.tsx     # Paywall feedback modal
-├── PaywallFeedbackModal.styles.ts
-└── paywallFeedbackStyles.ts
-```
-
-**PaywallFeedbackModal Kullanımı:**
-
-```typescript
-import { PaywallFeedbackModal } from '@umituz/react-native-subscription';
-
-<PaywallFeedbackModal
-  isVisible={showFeedback}
-  onClose={() => setShowFeedback(false)}
-  onSubmit={(feedback) => {
-    console.log('Feedback:', feedback);
-    analytics.track('paywall_feedback', feedback);
-  }}
-  translations={{
-    title: 'Tell us why',
-    placeholder: 'Share your thoughts...',
-    submit: 'Submit',
-  }}
-/>
-```
-
-### Section Components
-
-Section bileşenleri:
-
-```
-components/sections/
-└── SubscriptionSection.tsx       # Abonelik section'ı
-```
-
-**SubscriptionSection Kullanımı:**
-
-```typescript
-import { SubscriptionSection } from '@umituz/react-native-subscription';
-
-<SubscriptionSection
-  title="Subscription"
-  subscription={subscriptionData}
-  onPress={() => navigateToSubscription()}
-  translations={{
-    manage: 'Manage Subscription',
-    upgrade: 'Upgrade to Premium',
-  }}
-/>
-```
-
-## Screens
-
-### SubscriptionDetailScreen
-
-Abonelik detay ekranı:
-
-```typescript
-import { SubscriptionDetailScreen } from '@umituz/react-native-subscription';
-
-function App() {
-  return (
-    <Stack.Screen
-      name="SubscriptionDetail"
-      component={SubscriptionDetailScreen}
-      options={{
-        title: 'Subscription',
-      }}
-    />
-  );
-}
-
-// Veya doğrudan kullanım
-<SubscriptionDetailScreen
-  route={{
-    key: 'subscription',
-    name: 'SubscriptionDetail',
-    params: { userId: 'user-123' },
-  }}
-  navigation={navigation}
-/>
-```
-
-## Tip Tanımlamaları
-
-### Component Props
-
-```typescript
-// PremiumDetailsCard
-interface PremiumDetailsCardProps {
-  status: SubscriptionStatus;
-  onUpgradePress?: () => void;
-  onManagePress?: () => void;
-  style?: ViewStyle;
-  translations?: PremiumDetailsCardTranslations;
-}
-
-// PremiumStatusBadge
-interface PremiumStatusBadgeProps {
-  status: SubscriptionStatusType;
-  size?: 'small' | 'medium' | 'large';
-  showIcon?: boolean;
-  style?: ViewStyle;
-}
-
-// PaywallFeedbackModal
-interface PaywallFeedbackModalProps {
-  isVisible: boolean;
-  onClose: () => void;
-  onSubmit: (feedback: string) => void;
-  translations?: PaywallFeedbackTranslations;
-}
-```
-
-## Styling
-
-Component stilleri StyleSheet ile tanımlanır:
-
-```typescript
-import { premiumDetailsCardStyles } from '@umituz/react-native-subscription';
-
-// Özel stil override
-<PremiumDetailsCard
-  style={customStyles.card}
-  status={status}
-/>
-
-const customStyles = StyleSheet.create({
-  card: {
-    backgroundColor: 'custom-background',
-    borderRadius: 16,
-    padding: 20,
-  },
-});
-```
-
-## Translations
-
-Tüm component'ler translations desteği sunar:
-
-```typescript
-const translations = {
-  // PremiumDetailsCard
-  title: 'Premium',
-  active: 'Active',
-  expires: 'Expires on',
-  renews: 'Renews on',
-  manage: 'Manage Subscription',
-  upgrade: 'Upgrade to Premium',
-
-  // PaywallFeedbackModal
-  feedbackTitle: 'Tell us why',
-  feedbackPlaceholder: 'Share your thoughts...',
-  submit: 'Submit',
-  cancel: 'Cancel',
-};
-
-<PremiumDetailsCard translations={translations} status={status} />
-```
-
-## Theming
-
-Component'leri özelleştirin:
-
-```typescript
-import { ThemeProvider } from '@umituz/react-native-subscription';
-
-const customTheme = {
-  colors: {
-    primary: '#FF6B6B',
-    success: '#4CAF50',
-    warning: '#FF9800',
-    error: '#F44336',
-    background: '#FFFFFF',
-    text: '#000000',
-  },
-  fonts: {
-    title: { fontSize: 24, fontWeight: 'bold' },
-    body: { fontSize: 16, fontWeight: 'normal' },
-  },
-  spacing: {
-    small: 8,
-    medium: 16,
-    large: 24,
-  },
-};
-
-<ThemeProvider theme={customTheme}>
-  <YourApp />
-</ThemeProvider>
-```
-
-## Best Practices
-
-1. **Props Validation**: PropTypes veya TypeScript kullanın
-2. **Styling**: Inline style yerine StyleSheet kullanın
-3. **Translations**: Her zaman translation prop'u sağlayın
-4. **Loading States**: Yüklenme durumlarını gösterin
-5. **Error Handling**: Hataları kullanıcı dostu gösterin
-6. **Accessibility**: Accessibility özelliklerini ekleyin
-7. **Performance**: React.memo ve useMemo kullanın
-
-## Örnek: Premium Feature Card
-
-```typescript
-import React from 'react';
-import { View, Text, StyleSheet } from 'react-native';
-import { PremiumDetailsCard, usePremium } from '@umituz/react-native-subscription';
-
-function PremiumFeatureCard() {
-  const { isPremium, subscription } = usePremium();
-
-  if (!isPremium) {
-    return (
-      <View style={styles.locked}>
-        <Text>🔒 Premium Feature</Text>
-        <PremiumDetailsCard
-          status={{
-            type: 'free',
-            isActive: false,
-            isPremium: false,
-          }}
-          onUpgradePress={showPaywall}
-          translations={{
-            title: 'Upgrade Required',
-            upgrade: 'Go Premium',
-          }}
-        />
-      </View>
-    );
-  }
-
-  return (
-    <PremiumDetailsCard
-      status={subscription}
-      onManagePress={navigateToManage}
-      translations={{
-        title: 'Premium Active',
-        manage: 'Manage',
-      }}
-    />
-  );
-}
-
-const styles = StyleSheet.create({
-  locked: {
-    padding: 16,
-    backgroundColor: '#F5F5F5',
-    borderRadius: 12,
-  },
-});
-
-export default PremiumFeatureCard;
-```
-
-## Örnek: Full Screen Implementation
-
-```typescript
-import React from 'react';
-import { View, ScrollView, ActivityIndicator } from 'react-native';
-import {
-  SubscriptionDetailScreen,
-  useSubscription,
-  usePremium,
-} from '@umituz/react-native-subscription';
-
-function MySubscriptionScreen() {
-  const { subscription, isLoading } = useSubscription();
-  const { isPremium } = usePremium();
-
-  if (isLoading) {
-    return <ActivityIndicator />;
-  }
-
-  return (
-    <ScrollView>
-      <SubscriptionDetailScreen
-        route={{
-          key: 'subscription',
-          name: 'SubscriptionDetail',
-          params: {},
-        }}
-        navigation={navigation}
-      />
-
-      {!isPremium && (
-        <UpgradePrompt
-          onPress={() => navigation.navigate('Paywall')}
-        />
-      )}
-    </ScrollView>
-  );
-}
-```
-
-## Component Library
-
-Tüm component'leri export edin:
-
-```typescript
-// components/index.ts
-export * from './details';
-export * from './feedback';
-export * from './sections';
-
-// Kullanım
-import {
-  PremiumDetailsCard,
-  PremiumStatusBadge,
-  PaywallFeedbackModal,
-  SubscriptionSection,
-} from '@umituz/react-native-subscription';
-```
+UI/UX layer for the subscription system - React hooks, components, and screens.
+
+## Location
+
+**Directory**: `src/presentation/`
+
+**Type**: Layer
+
+## Strategy
+
+### Layer Responsibilities
+
+The Presentation Layer is responsible for:
+
+1. **State Management**
+   - React hooks for data fetching and mutations
+   - TanStack Query for server state management
+   - Local state management for UI state
+
+2. **UI Components**
+   - Reusable subscription components
+   - Feature gating UI elements
+   - Credit display components
+   - Paywall components
+
+3. **User Interaction**
+   - Handle user actions
+   - Display appropriate feedback
+   - Guide users through purchase flows
+   - Show upgrade prompts at right time
+
+### Architecture Pattern
+
+The presentation layer follows a layered architecture where:
+- Hooks manage state and data fetching at the top level
+- Components consume hooks and render UI
+- Screens compose multiple components together
+- All layers communicate with the domain layer for business logic
+
+### Integration Points
+
+- **Domain Layer**: Business logic and data access
+- **TanStack Query**: Server state management
+- **RevenueCat**: Purchase operations
+- **Navigation**: Screen routing
+
+## Restrictions
+
+### REQUIRED
+
+- **Type Safety**: All components MUST be typed with TypeScript
+- **Error Boundaries**: MUST implement error boundaries for all screens
+- **Loading States**: MUST show loading indicators during async operations
+- **User Feedback**: MUST provide feedback for all user actions
+
+### PROHIBITED
+
+- **NEVER** include business logic in components (use hooks instead)
+- **NEVER** make direct API calls from components (use hooks)
+- **DO NOT** store sensitive data in component state
+- **NEVER** hardcode strings (use localization)
+
+### CRITICAL SAFETY
+
+- **ALWAYS** validate props before rendering
+- **ALWAYS** handle loading and error states
+- **NEVER** trust client-side state for security decisions
+- **MUST** implement proper error boundaries
+- **ALWAYS** sanitize user inputs before display
+
+## AI Agent Guidelines
+
+### When Building Presentation Layer
+
+1. **Always** use hooks for data fetching and state management
+2. **Always** handle loading and error states
+3. **Always** provide user feedback for actions
+4. **Always** implement error boundaries
+5. **Never** include business logic in components
+
+### Integration Checklist
+
+- [ ] Use appropriate hooks for data access
+- [ ] Handle loading states
+- [ ] Handle error states
+- [ ] Implement error boundaries
+- [ ] Provide user feedback
+- [ ] Test with various data states
+- [ ] Test error scenarios
+- [ ] Ensure type safety
+- [ ] Use localization for all strings
+- [ ] Test accessibility
+
+### Common Patterns
+
+1. **Compound Components**: Build complex UIs from simple components
+2. **Render Props**: Share stateful logic between components
+3. **Custom Hooks**: Extract reusable stateful logic
+4. **Error Boundaries**: Prevent crashes from propagating
+5. **Loading Skeletons**: Show placeholder during loading
+6. **Optimistic Updates**: Update UI immediately, rollback on failure
+7. **Graceful Degradation**: Show limited version on error
+8. **Responsive Design**: Support different screen sizes
+
+## Related Documentation
+
+- **Hooks**: `hooks/README.md`
+- **Components**: `components/README.md`
+- **Screens**: `screens/README.md`
+- **Wallet Domain**: `../../domains/wallet/README.md`
+- **Paywall Domain**: `../../domains/paywall/README.md`
+- **RevenueCat**: `../../revenuecat/README.md`
+
+## Directory Structure
+
+The presentation layer contains:
+- **hooks/** - React hooks for state management (usePremium, useSubscription, useCredits, useDeductCredit, useFeatureGate)
+- **components/** - UI components organized by functionality
+  - **details/** - Detail cards, badges
+  - **feedback/** - Modals, feedback components
+  - **sections/** - Section components
+  - **paywall/** - Paywall components
+- **screens/** - Full-screen components (SubscriptionDetailScreen)