@umituz/react-native-subscription 2.14.99 → 2.14.100

package/src/presentation/README.md.bak

@@ -0,0 +1,172 @@
+# Presentation Layer
+
+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
+
+## Rules
+
+### Component Structure
+
+**CORRECT**: Proper component structure includes:
+- Define TypeScript interface for props
+- Import and use appropriate hooks for data fetching
+- Return loading indicator when data is fetching
+- Return error display when there's an error
+- Render actual component only when data is available
+
+**INCORRECT**: No loading/error handling
+- Don't render component without checking if data is loading
+- Don't display component without handling potential errors
+- Never assume data is always available immediately
+
+**INCORRECT**: Business logic in component
+- Don't use useEffect to fetch data directly
+- Don't manage complex state with useState for business logic
+- Never include data transformation logic in components
+
+### Hook Usage
+
+**CORRECT**: Use hooks for data fetching
+- Call useCredits to get credit balance with loading and error states
+- Call usePremium to check premium status
+- Always check if loading is true before rendering
+- Always check if error exists before rendering
+
+**INCORRECT**: Direct API calls in component
+- Don't use useEffect with axios or fetch to call APIs
+- Don't manage async operations manually in components
+- Never handle API responses directly in UI components
+
+### Error Boundaries
+
+**CORRECT**: Wrap screens with error boundaries
+- Import ErrorBoundary component
+- Create fallback error screen component
+- Wrap screen content with ErrorBoundary component
+- Pass fallback component to ErrorBoundary
+
+**INCORRECT**: No error boundary
+- Don't export screens without error boundary wrapper
+- Never let errors crash entire application
+- Don't assume components will never throw errors
+
+## 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)

package/src/presentation/components/README.md

@@ -2,182 +2,154 @@
 
 React Native UI components for subscription and paywall features.
 
-## Overview
-
-This directory contains reusable UI components built with `@umituz/react-native-design-system`. All components are generic and app-agnostic, requiring configuration props for app-specific behavior.
-
-## Component Structure
-
-```
-presentation/components/
-├── details/           # Subscription detail components
-│   ├── PremiumDetailsCard.md
-│   ├── PremiumStatusBadge.md
-│   ├── DetailRow.md
-│   └── CreditRow.md
-├── sections/          # Section components for settings
-│   └── SubscriptionSection.md
-└── feedback/          # User feedback components
-    └── PaywallFeedbackModal.md
-```
-
-## Components
-
-### Detail Components
-
-#### [PremiumDetailsCard](./details/PremiumDetailsCard.md)
-Complete card displaying subscription details, status, and credits.
-
-```typescript
-<PremiumDetailsCard
-  statusType="active"
-  isPremium={true}
-  expirationDate="January 15, 2025"
-  purchaseDate="January 15, 2024"
-  credits={[{ id: 'monthly', label: 'Credits', current: 50, total: 100 }]}
-  translations={translations}
-  onManageSubscription={handleManage}
-  onUpgrade={handleUpgrade}
-/>
-```
-
-#### [PremiumStatusBadge](./details/PremiumStatusBadge.md)
-Colored badge showing subscription status.
-
-```typescript
-<PremiumStatusBadge
-  status="active"
-  activeLabel="Active"
-  expiredLabel="Expired"
-  noneLabel="Free"
-  canceledLabel="Canceled"
-/>
-```
-
-#### [DetailRow](./details/DetailRow.md)
-Simple label-value row for displaying subscription details.
-
-```typescript
-<DetailRow
-  label="Expires"
-  value="January 15, 2025"
-  highlight={true}
-/>
-```
-
-#### [CreditRow](./details/CreditRow.md)
-Credit display with progress bar and color-coded thresholds.
-
-```typescript
-<CreditRow
-  label="Monthly Credits"
-  current={50}
-  total={100}
-  remainingLabel="credits remaining"
-/>
-```
-
-### Section Components
-
-#### [SubscriptionSection](./sections/SubscriptionSection.md)
-Settings section component with subscription details.
-
-```typescript
-<SubscriptionSection
-  config={subscriptionConfig}
-  onPress={() => navigation.navigate('SubscriptionDetails')}
-/>
-```
-
-### Feedback Components
-
-#### [PaywallFeedbackModal](./feedback/PaywallFeedbackModal.md)
-Modal for collecting user feedback on paywall decline.
-
-```typescript
-<PaywallFeedbackModal
-  visible={showFeedback}
-  onClose={() => setShowFeedback(false)}
-  onSubmit={(reason) => trackFeedback(reason)}
-/>
-```
-
-## Usage Patterns
-
-### In Settings Screen
-
-```typescript
-function SettingsScreen() {
-  const config = useSubscriptionSettingsConfig({
-    userId: user?.uid,
-    translations: englishTranslations,
-  });
-
-  return (
-    <ScrollView>
-      <SubscriptionSection
-        config={config.sectionConfig}
-        onPress={() => navigation.navigate('SubscriptionDetails')}
-      />
-    </ScrollView>
-  );
-}
-```
-
-### In Paywall Screen
-
-```typescript
-function PaywallScreen() {
-  const [showFeedback, setShowFeedback] = useState(false);
-
-  return (
-    <View>
-      <PaywallContent onClose={() => setShowFeedback(true)} />
-
-      <PaywallFeedbackModal
-        visible={showFeedback}
-        onClose={() => setShowFeedback(false)}
-        onSubmit={handleSubmitFeedback}
-      />
-    </View>
-  );
-}
-```
-
-## Design System Integration
-
-All components use `@umituz/react-native-design-system` for:
-
-- **Tokens**: `useAppDesignTokens()` for colors, spacing, radius
-- **Typography**: `AtomicText` for consistent text styling
-- **Theming**: Automatic dark mode support via design tokens
-
-## Styling Customization
-
-Components accept style overrides:
-
-```typescript
-<PremiumDetailsCard
-  translations={translations}
-  containerStyle={{
-    marginHorizontal: 16,
-    borderRadius: 12,
-  }}
-/>
-```
-
-## Best Practices
-
-1. **Use design tokens** - Leverage `useAppDesignTokens()` for consistency
-2. **Provide translations** - Ensure all text is localized
-3. **Handle all states** - Test premium, free, expired, canceled states
-4. **Test edge cases** - Zero credits, max credits, long text
-5. **Match design system** - Follow app's design language
-6. **Accessibility** - Ensure proper contrast and touch targets
-7. **Performance** - Memoize where appropriate
-
-## Related
-
-- [Hooks](../hooks/README.md)
-- [Screens](../screens/README.md)
-- [Design System](https://github.com/umituz/react-native-design-system)
+## Location
+
+**Directory**: `src/presentation/components/`
+
+**Type**: Component Library
+
+## Strategy
+
+### Component Categories
+
+Components are organized by functionality:
+
+1. **Details Components**
+   - CreditRow: Display credit balance and info
+   - DetailRow: Generic detail display row
+   - PremiumStatusBadge: Visual premium indicator
+   - PremiumDetailsCard: Premium subscription details
+
+2. **Feedback Components**
+   - PaywallFeedbackModal: User feedback collection
+   - Alert components: Warning and info displays
+
+3. **Section Components**
+   - SubscriptionSection: Subscription info section
+   - CreditsSection: Credits balance section
+
+4. **Paywall Components**
+   - PaywallModal: Upgrade/purchase modal
+   - Purchase options: Subscription and credit packages
+
+### Design Principles
+
+All components follow these principles:
+- **Reusable**: Composable and configurable
+- **Typed**: Full TypeScript support
+- **Accessible**: WCAG compliant where possible
+- **Testable**: Easy to test in isolation
+- **Themeable**: Support custom styling
+
+### Integration Points
+
+- **React Native**: Core UI framework
+- **Design System**: Shared UI components
+- **Localization**: i18n string support
+- **Theme**: Custom styling support
+
+## Restrictions
+
+### REQUIRED
+
+- **Props Typing**: All components MUST have TypeScript interfaces
+- **Default Props**: MUST provide sensible defaults
+- **Accessibility**: MUST implement accessibility labels
+- **Responsive**: MUST handle different screen sizes
+
+### PROHIBITED
+
+- **NEVER** hardcode colors or sizes (use theme)
+- **NEVER** include business logic in components
+- **DO NOT** make direct API calls
+- **NEVER** hardcode strings (use localization)
+
+### CRITICAL SAFETY
+
+- **ALWAYS** validate props before rendering
+- **ALWAYS** handle loading and error states
+- **NEVER** trust user input for security decisions
+- **MUST** implement proper error boundaries
+- **ALWAYS** sanitize user-provided content
+
+## AI Agent Guidelines
+
+### When Building Components
+
+1. **Always** define TypeScript interfaces for props
+2. **Always** use theme for styling (no hardcoded values)
+3. **Always** implement accessibility labels
+4. **Always** handle loading and error states
+5. **Never** include business logic in components
+
+### Integration Checklist
+
+- [ ] Define TypeScript interface for props
+- [ ] Use theme for all styling
+- [ ] Implement accessibility labels
+- [ ] Handle loading state
+- [ ] Handle error state
+- [ ] Provide sensible defaults
+- [ ] Test with different screen sizes
+- [ ] Test accessibility
+- [ ] Test with various prop combinations
+- [ ] Document component usage
+
+### Common Patterns
+
+1. **Compound Components**: Build complex UIs from simple parts
+2. **Render Props**: Share stateful logic
+3. **Slot Pattern**: Allow content injection
+4. **Control Props**: Make components controlled or uncontrolled
+5. **Asynchronous States**: Handle loading, error, success states
+6. **Responsive Design**: Adapt to different screen sizes
+7. **Theme Integration**: Use design system tokens
+8. **Accessibility First**: Include a11y from the start
+
+## Related Documentation
+
+- **Details Components**: `details/README.md`
+- **Feedback Components**: `feedback/README.md`
+- **Section Components**: `sections/README.md`
+- **Paywall Components**: `paywall/README.md`
+- **Design System**: External design system documentation
+- **Hooks**: `../hooks/README.md`
+
+## Component Examples
+
+### CreditRow
+
+Display user's credit balance with optional actions.
+
+Usage:
+- Set amount prop to number of credits
+- Set isLoading to true during data fetch
+- Provide onPress callback for navigation
+- Component displays credit count and handles tap
+
+### PremiumStatusBadge
+
+Visual indicator for premium subscription status.
+
+Usage:
+- Set isPremium to boolean status
+- Set tier to subscription level (gold, silver, etc.)
+- Component renders styled badge
+
+### PaywallModal
+
+Modal for subscription and credit purchase.
+
+Usage:
+- Set isVisible to boolean for show/hide
+- Provide onClose callback
+- Pass features array for premium features list
+- Modal handles purchase flow
+
+## Directory Structure
+
+The components directory contains:
+- **details/** - Detail display components (CreditRow, DetailRow, PremiumStatusBadge, PremiumDetailsCard)
+- **feedback/** - Feedback and alert components (PaywallFeedbackModal)
+- **sections/** - Section components (SubscriptionSection)
+- **paywall/** - Paywall components (PaywallModal)