@umituz/react-native-subscription 2.14.99 → 2.14.100

package/src/presentation/hooks/usePaywallVisibility.md

@@ -2,343 +2,94 @@
 
 Simple global state management for paywall visibility using external store.
 
-## Import
+## Location
 
-```typescript
-import {
-  usePaywallVisibility,
-  paywallControl
-} from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/usePaywallVisibility.ts`
 
-```typescript
-function usePaywallVisibility(): {
-  showPaywall: boolean;
-  setShowPaywall: (visible: boolean) => void;
-  openPaywall: () => void;
-  closePaywall: () => void;
-}
+**Type**: Hook
 
-// Direct control (non-React contexts)
-paywallControl: {
-  open: () => void;
-  close: () => void;
-  isOpen: () => boolean;
-}
-```
+## Strategy
 
-## Returns
+### Global Paywall State Management
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `showPaywall` | `boolean` | Current visibility state |
-| `setShowPaywall` | `(visible) => void` | Set visibility state |
-| `openPaywall` | `() => void` | Open paywall |
-| `closePaywall` | `() => void` | Close paywall |
+1. **External Store**: Use Zustand or similar for global state
+2. **Visibility Control**: Simple boolean for show/hide
+3. **Global Access**: Available from any component
+4. **Direct Control**: Provide paywallControl for non-React contexts
+5. **Single Instance**: One paywall modal at app root
+6. **State Persistence**: Maintain visibility across component unmounts
 
-## Basic Usage
+### Integration Points
 
-```typescript
-function PaywallModal() {
-  const { showPaywall, closePaywall } = usePaywallVisibility();
+- **App Root**: Paywall modal should be placed at app root
+- **Any Component**: Can trigger paywall from anywhere
+- **Deep Links**: Can open paywall from URLs
+- **Push Notifications**: Can open paywall from notifications
+- **usePremium**: For conditional display based on status
 
-  if (!showPaywall) return null;
+## Restrictions
 
-  return (
-    <Modal visible={showPaywall} onRequestClose={closePaywall}>
-      <PaywallContent onClose={closePaywall} />
-    </Modal>
-  );
-}
-```
+### REQUIRED
 
-## Advanced Usage
+- **Single Modal**: MUST place paywall modal once at app root
+- **Close Handler**: MUST provide close button in paywall
+- **Premium Check**: SHOULD hide paywall when user becomes premium
+- **Back Handler**: SHOULD handle Android back button
 
-### With App Root Setup
+### PROHIBITED
 
-```typescript
-function App() {
-  return (
-    <>
-      <YourAppNavigation />
-      <PaywallModal />
-    </>
-  );
-}
+- **NEVER** place multiple paywall modals in component tree
+- **NEVER** manage visibility locally (use this hook instead)
+- **DO NOT** show paywall too frequently
+- **DO NOT** trap users without exit option
 
-function PaywallModal() {
-  const { showPaywall, closePaywall } = usePaywallVisibility();
+### CRITICAL SAFETY
 
-  return (
-    <Modal visible={showPaywall} animationType="slide">
-      <PaywallScreen onClose={closePaywall} />
-    </Modal>
-  );
-}
-```
+- **ALWAYS** provide close button
+- **NEVER** trap users in paywall
+- **MUST** handle back button on Android
+- **ALWAYS** hide paywall after successful purchase
 
-### With Trigger Button
+## AI Agent Guidelines
 
-```typescript
-function PremiumFeature() {
-  const { openPaywall } = usePaywallVisibility();
+### When Implementing Paywall Visibility
 
-  return (
-    <Button
-      onPress={openPaywall}
-      title="Upgrade to Premium"
-    />
-  );
-}
-```
+1. **Always** place paywall modal once at app root
+2. **Always** provide close button
+3. **Always** use openPaywall/closePaywall functions
+4. **Always** hide paywall after successful purchase
+5. **Never** manage visibility locally in components
 
-### With Direct Control (Non-React)
+### Integration Checklist
 
-```typescript
-// In app initializer or non-React code
-import { paywallControl } from '@umituz/react-native-subscription';
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Place paywall modal once at app root
+- [ ] Use openPaywall to show paywall
+- [ ] Use closePaywall to hide paywall
+- [ ] Provide close button in paywall
+- [ ] Handle Android back button
+- [ ] Hide paywall when user becomes premium
+- [ ] Test paywall opens from any component
+- [ ] Test paywallControl for non-React contexts
+- [ ] Test deep link integration
 
-function showPaywallFromDeepLink(url: URL) {
-  if (url.pathname === '/upgrade') {
-    paywallControl.open();
-  }
-}
+### Common Patterns
 
-function checkAndShowPaywall() {
-  if (!paywallControl.isOpen()) {
-    paywallControl.open();
-  }
-}
-```
+1. **App Root Setup**: Single modal instance at app root
+2. **Trigger Button**: Any component can open paywall
+3. **Direct Control**: Use paywallControl in non-React code
+4. **Conditional Display**: Auto-show based on user status
+5. **History/Navigation**: Handle navigation with paywall
+6. **Timeout/Auto-Close**: Auto-close after timeout
+7. **Deep Links**: Open from URL schemes
 
-### With Conditional Display
+## Related Documentation
 
-```typescript
-function ConditionalPaywall() {
-  const { showPaywall, openPaywall, closePaywall } = usePaywallVisibility();
-  const { isPremium } = usePremium();
-
-  useEffect(() => {
-    // Auto-show paywall for free users on certain screens
-    if (!isPremium && someCondition) {
-      openPaywall();
-    }
-  }, [isPremium]);
-
-  if (isPremium) return null; // Don't show for premium users
-
-  return (
-    <Modal visible={showPaywall}>
-      <PaywallContent onClose={closePaywall} />
-    </Modal>
-  );
-}
-```
-
-### With History/Navigation
-
-```typescript
-function PaywallWithHistory() {
-  const { showPaywall, closePaywall, openPaywall } = usePaywallVisibility();
-  const navigation = useNavigation();
-
-  useEffect(() => {
-    const unsubscribe = navigation.addListener('focus', () => {
-      // Show paywall when returning to certain screens
-      if (shouldShowPaywall()) {
-        openPaywall();
-      }
-    });
-
-    return unsubscribe;
-  }, [navigation]);
-
-  const handleClose = () => {
-    closePaywall();
-    navigation.goBack();
-  };
-
-  return (
-    <Modal visible={showPaywall}>
-      <PaywallContent onClose={handleClose} />
-    </Modal>
-  );
-}
-```
-
-## Examples
-
-### Global Paywall System
-
-```typescript
-// App.tsx
-function App() {
-  return (
-    <PaywallProvider>
-      <Navigation />
-      <GlobalPaywall />
-    </PaywallProvider>
-  );
-}
-
-// components/GlobalPaywall.tsx
-function GlobalPaywall() {
-  const { showPaywall, closePaywall } = usePaywallVisibility();
-
-  return (
-    <Modal visible={showPaywall} animationType="slide">
-      <PaywallScreen onClose={closePaywall} />
-    </Modal>
-  );
-}
-
-// Any component can trigger the paywall
-function UpgradeButton() {
-  const { openPaywall } = usePaywallVisibility();
-  return <Button onPress={openPaywall} title="Upgrade" />;
-}
-```
-
-### With Context Integration
-
-```typescript
-function PaywallWithContext() {
-  const { showPaywall, closePaywall, setShowPaywall } = usePaywallVisibility();
-  const { isPremium } = usePremium();
-
-  // Close paywall when user becomes premium
-  useEffect(() => {
-    if (isPremium && showPaywall) {
-      setShowPaywall(false);
-    }
-  }, [isPremium, showPaywall]);
-
-  if (isPremium) return null;
-
-  return (
-    <Modal visible={showPaywall}>
-      <PaywallScreen onClose={closePaywall} />
-    </Modal>
-  );
-}
-```
-
-### With Timeout/Auto-Close
-
-```typescript
-function TimedPaywall() {
-  const { showPaywall, closePaywall } = usePaywallVisibility();
-
-  useEffect(() => {
-    if (!showPaywall) return;
-
-    // Auto-close after 30 seconds
-    const timer = setTimeout(() => {
-      closePaywall();
-    }, 30000);
-
-    return () => clearTimeout(timer);
-  }, [showPaywall, closePaywall]);
-
-  return (
-    <Modal visible={showPaywall}>
-      <PaywallContent onClose={closePaywall} />
-    </Modal>
-  );
-}
-```
-
-### With Back Handler
-
-```typescript
-function PaywallWithBackHandler() {
-  const { showPaywall, closePaywall } = usePaywallVisibility();
-
-  useBackHandler(showPaywall, () => {
-    closePaywall();
-    return true; // Prevent default back behavior
-  });
-
-  return (
-    <Modal visible={showPaywall}>
-      <PaywallContent onClose={closePaywall} />
-    </Modal>
-  );
-}
-```
-
-### From Deep Link
-
-```typescript
-// Deep link handler
-import { paywallControl } from '@umituz/react-native-subscription';
-import { Linking } from 'react-native';
-
-Linking.addEventListener('url', ({ url }) => {
-  const parsed = new URL(url);
-
-  if (parsed.pathname === '/upgrade') {
-    paywallControl.open();
-  }
-
-  if (parsed.searchParams.get('show_paywall') === 'true') {
-    paywallControl.open();
-  }
-});
-```
-
-### From Push Notification
-
-```typescript
-// Push notification handler
-import { paywallControl } from '@umituz/react-native-subscription';
-import messaging from '@react-native-firebase/messaging';
-
-messaging().onNotificationOpenedApp((remoteMessage) => {
-  if (remoteMessage.data?.type === 'paywall') {
-    paywallControl.open();
-  }
-});
-
-// Or when app is in background
-messaging().setBackgroundMessageHandler(async (remoteMessage) => {
-  if (remoteMessage.data?.show_paywall) {
-    // Store flag to show paywall when app opens
-    AsyncStorage.setItem('pending_paywall', 'true');
-  }
-});
-
-// Then in your app
-useEffect(() => {
-  AsyncStorage.getItem('pending_paywall').then((value) => {
-    if (value === 'true') {
-      paywallControl.open();
-      AsyncStorage.removeItem('pending_paywall');
-    }
-  });
-}, []);
-```
-
-## Best Practices
-
-1. **Single modal instance** - Place paywall once at app root
-2. **Global access** - Use `paywallControl` for non-React contexts
-3. **Clean close** - Always provide close button
-4. **Back handler** - Handle Android back button
-5. **State persistence** - Don't rely on component state
-6. **Auto-close for premium** - Hide when user subscribes
-7. **Deeplink support** - Open from URLs and notifications
-
-## Related Hooks
-
-- **usePaywallOperations** - For paywall purchase operations
-- **usePremium** - For subscription status
-- **usePaywall** - For complete paywall management
-
-## See Also
-
-- [Paywall Screen](../screens/README.md)
-- [Paywall Components](../components/paywall/README.md)
-- [Modal Integration](../../../docs/MODAL_INTEGRATION.md)
+- **usePaywallOperations**: For paywall purchase operations
+- **usePremium**: For subscription status
+- **usePaywall**: For complete paywall management
+- **Paywall Screen**: `src/presentation/screens/README.md`
+- **Paywall Components**: `src/presentation/components/paywall/README.md`
+- **Modal Integration**: `src/docs/MODAL_INTEGRATION.md`