@umituz/react-native-subscription 2.14.97 → 2.14.98

package/src/presentation/components/details/PremiumDetailsCard.md

@@ -0,0 +1,266 @@
+# PremiumDetailsCard Component
+
+Premium subscription details card component.
+
+## Import
+
+```typescript
+import { PremiumDetailsCard } from '@umituz/react-native-subscription';
+```
+
+## Props
+
+```typescript
+interface PremiumDetailsCardProps {
+  status: SubscriptionStatus;
+  onUpgradePress?: () => void;
+  onManagePress?: () => void;
+  style?: ViewStyle;
+  translations?: PremiumDetailsCardTranslations;
+}
+```
+
+## Props Reference
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `status` | `SubscriptionStatus` | Yes | Subscription status object |
+| `onUpgradePress` | `() => void` | No | Callback when upgrade button pressed |
+| `onManagePress` | `() => void` | No | Callback when manage button pressed |
+| `style` | `ViewStyle` | No | Custom container style |
+| `translations` | `PremiumDetailsCardTranslations` | No | Custom translations |
+
+## Basic Usage
+
+```typescript
+function MyScreen() {
+  const { subscription } = usePremium();
+
+  return (
+    <PremiumDetailsCard
+      status={subscription}
+      onUpgradePress={() => console.log('Upgrade')}
+      onManagePress={() => console.log('Manage')}
+    />
+  );
+}
+```
+
+## Examples
+
+### With Custom Translations
+
+```typescript
+<PremiumDetailsCard
+  status={subscription}
+  translations={{
+    title: 'Premium',
+    active: 'Aktif',
+    inactive: 'Aktif Değil',
+    expires: 'Son Kullanma',
+    renews: 'Yenileniyor',
+    manage: 'Yönet',
+    upgrade: 'Yükselt',
+    lifetime: 'Ömür Boyu',
+  }}
+/>
+```
+
+### With Custom Styling
+
+```typescript
+const customStyles = StyleSheet.create({
+  card: {
+    backgroundColor: '#FF6B6B',
+    borderRadius: 16,
+    padding: 20,
+  },
+  title: {
+    color: '#fff',
+    fontSize: 24,
+  },
+});
+
+<PremiumDetailsCard
+  status={subscription}
+  style={customStyles.card}
+  titleStyle={customStyles.title}
+/>
+```
+
+### Without Buttons
+
+```typescript
+<PremiumDetailsCard
+  status={subscription}
+  showManageButton={false}
+  showUpgradeButton={false}
+/>
+```
+
+## Translations Interface
+
+```typescript
+interface PremiumDetailsCardTranslations {
+  title?: string;           // 'Premium'
+  status?: string;          // 'Active' or 'Inactive'
+  expires?: string;         // 'Expires on'
+  renews?: string;          // 'Renews on'
+  manage?: string;          // 'Manage Subscription'
+  upgrade?: string;         // 'Upgrade to Premium'
+  lifetime?: string;        // 'Lifetime Access'
+}
+```
+
+## Component Structure
+
+```
+PremiumDetailsCard
+├── Container
+│   ├── Header
+│   │   ├── Title (Premium Badge)
+│   │   └── Status (Active/Inactive)
+│   ├── Details
+│   │   ├── Expiration Date
+│   │   ├── Renewal Status
+│   │   └── Product Info
+│   └── Footer
+│       ├── Manage Button (if premium)
+│       └── Upgrade Button (if free)
+```
+
+## Styling
+
+### Default Styles
+
+```typescript
+const defaultStyles = StyleSheet.create({
+  container: {
+    backgroundColor: '#fff',
+    borderRadius: 12,
+    padding: 16,
+    margin: 16,
+    shadowColor: '#000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.1,
+    shadowRadius: 4,
+    elevation: 3,
+  },
+  header: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    marginBottom: 12,
+  },
+  title: {
+    fontSize: 20,
+    fontWeight: 'bold',
+    color: '#000',
+  },
+  badge: {
+    backgroundColor: '#FFD700',
+    paddingHorizontal: 8,
+    paddingVertical: 4,
+    borderRadius: 12,
+  },
+});
+```
+
+### Theme Customization
+
+```typescript
+const darkTheme = {
+  container: {
+    backgroundColor: '#1a1a1a',
+  },
+  title: {
+    color: '#fff',
+  },
+  text: {
+    color: '#ccc',
+  },
+};
+
+<PremiumDetailsCard
+  status={subscription}
+  theme={darkTheme}
+/>
+```
+
+## Accessibility
+
+The component includes:
+
+- ✅ Accessibility label
+- ✅ Accessibility hint
+- ✅ Screen reader support
+- ✅ Minimum touch target size (44x44)
+
+```typescript
+<PremiumDetailsCard
+  status={subscription}
+  accessibilityLabel="Premium subscription details"
+  accessibilityHint="Shows your premium subscription status and options"
+/>
+```
+
+## Best Practices
+
+1. **Provide callbacks** - Always handle upgrade/manage presses
+2. **Show for premium users** - Display current subscription info
+3. **Show for free users** - Encourage upgrade
+4. **Update on purchase** - Refetch after subscription change
+5. **Handle loading** - Show skeleton while loading
+
+## Complete Example
+
+```typescript
+function SubscriptionScreen() {
+  const { subscription, isLoading, refetch } = usePremium();
+
+  useFocusEffect(
+    useCallback(() => {
+      refetch();
+    }, [refetch])
+  );
+
+  if (isLoading) {
+    return <PremiumDetailsCardSkeleton />;
+  }
+
+  if (!subscription?.isPremium) {
+    return (
+      <PremiumDetailsCard
+        status={{
+          type: 'free',
+          isActive: false,
+          isPremium: false,
+        }}
+        onUpgradePress={() => navigation.navigate('Paywall')}
+      />
+    );
+  }
+
+  return (
+    <ScrollView>
+      <PremiumDetailsCard
+        status={subscription}
+        onManagePress={handleManageSubscription}
+      />
+
+      {/* Additional premium features */}
+      <PremiumFeaturesList />
+    </ScrollView>
+  );
+}
+```
+
+## Related Components
+
+- **PremiumStatusBadge** - Compact premium badge
+- **SubscriptionSection** - Full subscription section
+- **PaywallModal** - Upgrade paywall
+
+## See Also
+
+- [Details Components README](../details/README.md)
+- [PremiumStatusBadge](./PremiumStatusBadge.md)

package/src/presentation/components/details/PremiumStatusBadge.md

@@ -0,0 +1,266 @@
+# PremiumStatusBadge Component
+
+Displays subscription status as a colored badge component.
+
+## Import
+
+```typescript
+import { PremiumStatusBadge } from '@umituz/react-native-subscription';
+```
+
+## Signature
+
+```typescript
+interface PremiumStatusBadgeProps {
+  status: SubscriptionStatusType;
+  activeLabel: string;
+  expiredLabel: string;
+  noneLabel: string;
+  canceledLabel: string;
+}
+
+type SubscriptionStatusType = 'active' | 'expired' | 'none' | 'canceled';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `status` | `SubscriptionStatusType` | **Required** | Current subscription status |
+| `activeLabel` | `string` | **Required** | Label for active status |
+| `expiredLabel` | `string` | **Required** | Label for expired status |
+| `noneLabel` | `string` | **Required** | Label for no subscription |
+| `canceledLabel` | `string` | **Required** | Label for canceled status |
+
+## Basic Usage
+
+```typescript
+function SubscriptionStatus() {
+  const { isPremium } = usePremium();
+
+  return (
+    <PremiumStatusBadge
+      status={isPremium ? 'active' : 'none'}
+      activeLabel="Active"
+      expiredLabel="Expired"
+      noneLabel="Free"
+      canceledLabel="Canceled"
+    />
+  );
+}
+```
+
+## Advanced Usage
+
+### With Dynamic Status
+
+```typescript
+function DynamicStatusBadge() {
+  const { status, isActive, isExpired } = useSubscriptionStatus();
+
+  const getStatusType = (): SubscriptionStatusType => {
+    if (!status) return 'none';
+    if (isExpired) return 'expired';
+    if (isActive) return 'active';
+    return 'canceled';
+  };
+
+  return (
+    <PremiumStatusBadge
+      status={getStatusType()}
+      activeLabel="Active"
+      expiredLabel="Expired"
+      noneLabel="Free"
+      canceledLabel="Canceled"
+    />
+  );
+}
+```
+
+### With Custom Labels
+
+```typescript
+function CustomStatusBadge() {
+  const { isActive } = usePremium();
+
+  return (
+    <PremiumStatusBadge
+      status={isActive ? 'active' : 'none'}
+      activeLabel="✨ Premium"
+      expiredLabel="⚠️ Expired"
+      noneLabel="Free Tier"
+      canceledLabel="❌ Canceled"
+    />
+  );
+}
+```
+
+### With Localization
+
+```typescript
+function LocalizedStatusBadge() {
+  const { t } = useTranslation();
+  const { status } = useSubscriptionStatus();
+
+  return (
+    <PremiumStatusBadge
+      status={status.type}
+      activeLabel={t('subscription.status.active')}
+      expiredLabel={t('subscription.status.expired')}
+      noneLabel={t('subscription.status.free')}
+      canceledLabel={t('subscription.status.canceled')}
+    />
+  );
+}
+```
+
+## Badge Colors
+
+The component automatically applies appropriate colors based on status:
+
+| Status | Background Color | Text Color |
+|--------|-----------------|------------|
+| `active` | Success (green) | On-primary |
+| `expired` | Error (red) | On-primary |
+| `none` | Tertiary text | On-primary |
+| `canceled` | Warning (orange) | On-primary |
+
+## Examples
+
+### In Header
+
+```typescript
+function SubscriptionHeader() {
+  const { status } = useSubscriptionStatus();
+
+  return (
+    <View style={styles.header}>
+      <Text style={styles.title}>My Subscription</Text>
+
+      <PremiumStatusBadge
+        status={status.type}
+        activeLabel="Active"
+        expiredLabel="Expired"
+        noneLabel="Free"
+        canceledLabel="Canceled"
+      />
+    </View>
+  );
+}
+```
+
+### With Icon
+
+```typescript
+function StatusWithIcon() {
+  const { isActive } = usePremium();
+
+  return (
+    <View style={styles.container}>
+      <Icon
+        name={isActive ? 'check-circle' : 'circle'}
+        size={20}
+        color={isActive ? 'green' : 'gray'}
+      />
+
+      <PremiumStatusBadge
+        status={isActive ? 'active' : 'none'}
+        activeLabel="Active"
+        expiredLabel="Expired"
+        noneLabel="Free"
+        canceledLabel="Canceled"
+      />
+    </View>
+  );
+}
+```
+
+### Status List
+
+```typescript
+function StatusList() {
+  const statuses: SubscriptionStatusType[] = ['active', 'expired', 'none', 'canceled'];
+
+  return (
+    <View>
+      {statuses.map((status) => (
+        <View key={status} style={styles.row}>
+          <Text>{status}</Text>
+
+          <PremiumStatusBadge
+            status={status}
+            activeLabel="Active"
+            expiredLabel="Expired"
+            noneLabel="Free"
+            canceledLabel="Canceled"
+          />
+        </View>
+      ))}
+    </View>
+  );
+}
+```
+
+### Compact Badge
+
+```typescript
+function CompactBadge() {
+  const { isActive } = usePremium();
+
+  return (
+    <View style={styles.compactContainer}>
+      <PremiumStatusBadge
+        status={isActive ? 'active' : 'none'}
+        activeLabel="Premium"
+        expiredLabel="Expired"
+        noneLabel="Free"
+        canceledLabel="Canceled"
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  compactContainer: {
+    transform: [{ scale: 0.85 }], // Smaller size
+  },
+});
+```
+
+## Styling
+
+The badge uses design tokens for consistent styling:
+
+```typescript
+// Internal styles (simplified)
+badge: {
+  paddingHorizontal: tokens.spacing.sm,
+  paddingVertical: tokens.spacing.xs,
+  borderRadius: tokens.radius.xs,
+  backgroundColor: statusColor, // Dynamic based on status
+},
+badgeText: {
+  fontWeight: '600',
+  color: tokens.colors.onPrimary,
+}
+```
+
+## Best Practices
+
+1. **Provide all labels** - Ensure all four status labels are provided
+2. **Use consistent labels** - Keep labels consistent across app
+3. **Localize labels** - Translate labels for i18n
+4. **Check status first** - Determine correct status type
+5. **Handle all states** - Cover active, expired, none, canceled
+6. **Test colors** - Verify colors work with your theme
+
+## Related Components
+
+- **PremiumDetailsCard** - Uses this badge component
+- **SubscriptionSection** - Displays badge in settings
+- **DetailRow** - Displays status as detail row
+
+## See Also
+
+- [SubscriptionStatus Entity](../../../domain/entities/SubscriptionStatus.md)
+- [Status Utilities](../../../utils/subscriptionUtils.md)