@umituz/react-native-subscription 2.14.96 → 2.14.98

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

@@ -0,0 +1,337 @@
+# CreditRow Component
+
+Displays credit information with label, count badge, and progress bar.
+
+## Import
+
+```typescript
+import { CreditRow } from '@umituz/react-native-subscription';
+```
+
+## Signature
+
+```typescript
+interface CreditRowProps {
+  label: string;
+  current: number;
+  total: number;
+  remainingLabel?: string;
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | **Required** | Credit type label |
+| `current` | `number` | **Required** | Current credit amount |
+| `total` | `number` | **Required** | Maximum credit amount |
+| `remainingLabel` | `string` | `undefined` | Label for remaining text |
+
+## Basic Usage
+
+```typescript
+function CreditsDisplay() {
+  const { credits } = useCredits();
+
+  return (
+    <CreditRow
+      label="Monthly Credits"
+      current={credits}
+      total={100}
+      remainingLabel="credits remaining"
+    />
+  );
+}
+```
+
+## Advanced Usage
+
+### With Multiple Credit Types
+
+```typescript
+function MultipleCredits() {
+  const { credits: monthlyCredits } = useCredits();
+  const bonusCredits = 50;
+
+  return (
+    <View>
+      <CreditRow
+        label="Monthly Credits"
+        current={monthlyCredits}
+        total={100}
+        remainingLabel="credits left"
+      />
+
+      <CreditRow
+        label="Bonus Credits"
+        current={bonusCredits}
+        total={50}
+        remainingLabel="bonus credits"
+      />
+
+      <CreditRow
+        label="Reward Credits"
+        current={25}
+        total={100}
+        remainingLabel="rewards"
+      />
+    </View>
+  );
+}
+```
+
+### With Dynamic Updates
+
+```typescript
+function LiveCredits() {
+  const { credits, refetch } = useCredits();
+
+  useEffect(() => {
+    const interval = setInterval(() => {
+      refetch();
+    }, 30000); // Update every 30 seconds
+
+    return () => clearInterval(interval);
+  }, [refetch]);
+
+  return (
+    <CreditRow
+      label="Credits"
+      current={credits}
+      total={100}
+      remainingLabel="remaining"
+    />
+  );
+}
+```
+
+### With Warning Thresholds
+
+```typescript
+function CreditWarning() {
+  const { credits } = useCredits();
+
+  return (
+    <CreditRow
+      label="Monthly Credits"
+      current={credits}
+      total={100}
+      remainingLabel={credits < 20 ? '⚠️ Low balance!' : 'credits remaining'}
+    />
+  );
+}
+```
+
+### Complete Credit Dashboard
+
+```typescript
+function CreditDashboard() {
+  const { credits: monthlyCredits, transactions } = useCredits();
+  const { purchasedAt } = useCredits();
+
+  // Calculate bonus credits from transactions
+  const bonusCredits = transactions
+    .filter(tx => tx.type === 'bonus')
+    .reduce((sum, tx) => sum + tx.amount, 0);
+
+  // Calculate total usage
+  const totalUsed = 100 - monthlyCredits + bonusCredits;
+
+  return (
+    <Card>
+      <Text style={styles.title}>Your Credits</Text>
+
+      <CreditRow
+        label="Monthly Credits"
+        current={monthlyCredits}
+        total={100}
+        remainingLabel="credits this month"
+      />
+
+      <CreditRow
+        label="Bonus Credits"
+        current={bonusCredits}
+        total={50}
+        remainingLabel="bonus credits"
+      />
+
+      <View style={styles.footer}>
+        <Text style={styles.info}>
+          Resets on {getNextMonthDate(purchasedAt).toLocaleDateString()}
+        </Text>
+      </View>
+    </Card>
+  );
+}
+```
+
+## Progress Bar Colors
+
+The progress bar color changes based on percentage:
+
+| Percentage | Color | Visual |
+|------------|-------|--------|
+| 0-20% | Error (red) | ██████░░░░░░░░░░░░░ |
+| 21-50% | Warning (orange) | ████████████░░░░░░ |
+| 51-100% | Success (green) | ████████████████████ |
+
+## Examples
+
+### In Subscription Settings
+
+```typescript
+function SubscriptionCredits() {
+  const { credits, isLoading } = useCredits();
+
+  if (isLoading) return <LoadingSkeleton />;
+
+  return (
+    <View style={styles.section}>
+      <Text style={styles.sectionTitle}>Credits</Text>
+
+      <CreditRow
+        label="Monthly Allowance"
+        current={credits}
+        total={100}
+        remainingLabel="credits"
+      />
+    </View>
+  );
+}
+```
+
+### With Purchase Link
+
+```typescript
+function CreditWithPurchase() {
+  const { credits } = useCredits();
+
+  const isLow = credits < 20;
+
+  return (
+    <View>
+      <CreditRow
+        label="Credits"
+        current={credits}
+        total={100}
+        remainingLabel="remaining"
+      />
+
+      {isLow && (
+        <Button
+          onPress={() => navigation.navigate('CreditPackages')}
+          title="Get More Credits"
+          style={styles.purchaseButton}
+        />
+      )}
+    </View>
+  );
+}
+```
+
+### With Feature Costs
+
+```typescript
+function FeatureCostDisplay() {
+  const { credits } = useCredits();
+
+  const features = [
+    { name: 'AI Generation', cost: 5 },
+    { name: 'Advanced Export', cost: 3 },
+    { name: 'Cloud Sync', cost: 1 },
+  ];
+
+  return (
+    <View>
+      <CreditRow
+        label="Available Credits"
+        current={credits}
+        total={100}
+        remainingLabel="credits"
+      />
+
+      <View style={styles.divider} />
+
+      {features.map((feature) => (
+        <DetailRow
+          key={feature.name}
+          label={feature.name}
+          value={`${feature.cost} credits`}
+        />
+      ))}
+    </View>
+  );
+}
+```
+
+## Component Layout
+
+```
+┌─────────────────────────────────────┐
+│ Monthly Credits        [50/100]     │
+│ ████████████░░░░░░░░░░░░░░░░        │
+│ 50 credits remaining               │
+└─────────────────────────────────────┘
+```
+
+## Styling
+
+```typescript
+const styles = StyleSheet.create({
+  container: {
+    gap: 8,
+    marginVertical: 4,
+  },
+  header: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+  },
+  label: {
+    fontWeight: '500',
+  },
+  badge: {
+    paddingHorizontal: 8,
+    paddingVertical: 2,
+    borderRadius: 6,
+    backgroundColor: tokens.colors.surfaceSecondary,
+  },
+  count: {
+    fontWeight: '600',
+  },
+  progressBar: {
+    height: 8,
+    borderRadius: 4,
+    overflow: 'hidden',
+    backgroundColor: tokens.colors.surfaceSecondary,
+  },
+  progressFill: {
+    height: '100%',
+    borderRadius: 4,
+    backgroundColor: progressColor, // Dynamic based on percentage
+  },
+});
+```
+
+## Best Practices
+
+1. **Show total always** - Display max credits for context
+2. **Update regularly** - Keep credits current
+3. **Color code thresholds** - Use colors for low/high amounts
+4. **Provide context** - Explain credit reset周期
+5. **Link to purchase** - Add purchase option when low
+6. **Test edge cases** - Zero credits, max credits, negative values
+7. **Format numbers** - Use appropriate number formatting
+
+## Related Components
+
+- **PremiumDetailsCard** - Contains credit rows
+- **DetailRow** - Simple label-value row
+- **SubscriptionSection** - Section with credits
+
+## See Also
+
+- [useCredits](../../hooks/useCredits.md)
+- [Credits Entity](../../../domains/wallet/domain/entities/Credits.md)
+- [Credits README](../../../../domains/wallet/README.md)

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

@@ -0,0 +1,283 @@
+# DetailRow Component
+
+Simple row component displaying a label-value pair for subscription details.
+
+## Import
+
+```typescript
+import { DetailRow } from '@umituz/react-native-subscription';
+```
+
+## Signature
+
+```typescript
+interface DetailRowProps {
+  label: string;
+  value: string;
+  highlight?: boolean;
+  style?: ViewStyle;
+  labelStyle?: TextStyle;
+  valueStyle?: TextStyle;
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | **Required** | Row label (left side) |
+| `value` | `string` | **Required** | Row value (right side) |
+| `highlight` | `boolean` | `false` | Highlight value in warning color |
+| `style` | `ViewStyle` | `undefined` | Container style override |
+| `labelStyle` | `TextStyle` | `undefined` | Label text style override |
+| `valueStyle` | `TextStyle` | `undefined` | Value text style override |
+
+## Basic Usage
+
+```typescript
+function SubscriptionDetails() {
+  return (
+    <View>
+      <DetailRow
+        label="Status"
+        value="Active"
+      />
+      <DetailRow
+        label="Expires"
+        value="January 15, 2025"
+      />
+      <DetailRow
+        label="Purchased"
+        value="January 15, 2024"
+      />
+    </View>
+  );
+}
+```
+
+## Advanced Usage
+
+### With Highlight
+
+```typescript
+function ExpiringSoonRow() {
+  const daysRemaining = 3;
+
+  return (
+    <DetailRow
+      label="Expires"
+      value={expirationDate.toLocaleDateString()}
+      highlight={daysRemaining <= 7} // Highlight if expiring soon
+    />
+  );
+}
+```
+
+### With Custom Styling
+
+```typescript
+function CustomDetailRow() {
+  return (
+    <DetailRow
+      label="Subscription Type"
+      value="Premium Yearly"
+      style={{
+        paddingVertical: 12,
+        paddingHorizontal: 16,
+        backgroundColor: '#F5F5F5',
+      }}
+      labelStyle={{
+        fontWeight: '600',
+        color: '#333',
+      }}
+      valueStyle={{
+        fontWeight: '700',
+        color: '#4CAF50',
+      }}
+    />
+  );
+}
+```
+
+### In Subscription Card
+
+```typescript
+function SubscriptionCard() {
+  const { status, expirationDate, willRenew } = useSubscriptionStatus();
+
+  return (
+    <Card>
+      <DetailRow
+        label="Status"
+        value={status.isActive ? 'Active' : 'Inactive'}
+      />
+
+      {expirationDate && (
+        <DetailRow
+          label="Expires"
+          value={expirationDate.toLocaleDateString()}
+          highlight={!willRenew}
+        />
+      )}
+
+      <DetailRow
+        label="Auto-renew"
+        value={willRenew ? 'Enabled' : 'Disabled'}
+      />
+    </Card>
+  );
+}
+```
+
+## Color Options
+
+### Default Colors
+
+```typescript
+// Label color (left side)
+labelStyle = {
+  color: tokens.colors.textSecondary, // Gray
+}
+
+// Value color (right side)
+valueStyle = {
+  color: tokens.colors.textPrimary, // Black
+  fontWeight: '500',
+}
+```
+
+### Highlight Colors
+
+```typescript
+// When highlight={true}
+valueStyle = {
+  color: tokens.colors.warning, // Orange/Yellow
+  fontWeight: '500',
+}
+```
+
+## Examples
+
+### Subscription Info List
+
+```typescript
+function SubscriptionInfo() {
+  const { status, expirationDate, purchaseDate, isLifetime } = useSubscriptionDetails();
+
+  return (
+    <View style={styles.section}>
+      <Text style={styles.title}>Subscription Details</Text>
+
+      <DetailRow
+        label="Plan"
+        value={status.productId || 'Free'}
+      />
+
+      {status.isActive && !isLifetime && (
+        <>
+          {expirationDate && (
+            <DetailRow
+              label="Expires"
+              value={expirationDate.toLocaleDateString()}
+              highlight={true}
+            />
+          )}
+
+          {purchaseDate && (
+            <DetailRow
+              label="Purchased"
+              value={purchaseDate.toLocaleDateString()}
+            />
+          )}
+        </>
+      )}
+
+      {isLifetime && (
+        <DetailRow
+          label="Type"
+          value="Lifetime Access"
+        />
+      )}
+    </View>
+  );
+}
+```
+
+### With Icons
+
+```typescript
+function IconDetailRow() {
+  return (
+    <View style={styles.row}>
+      <Icon name="calendar" size={20} color="#666" />
+
+      <DetailRow
+        label="Expiration"
+        value="December 31, 2025"
+        style={{ flex: 1, marginLeft: 8 }}
+      />
+    </View>
+  );
+}
+```
+
+### Compact Layout
+
+```typescript
+function CompactDetails() {
+  return (
+    <View>
+      <DetailRow
+        label="Price"
+        value="$9.99/month"
+        style={{ paddingVertical: 4 }}
+      />
+      <DetailRow
+        label="Duration"
+        value="Monthly"
+        style={{ paddingVertical: 4 }}
+      />
+      <DetailRow
+        label="Features"
+        value="Unlimited access"
+        style={{ paddingVertical: 4 }}
+      />
+    </View>
+  );
+}
+```
+
+## Best Practices
+
+1. **Use consistent labels** - Keep labels similar across screens
+2. **Format values** - Ensure proper date/currency formatting
+3. **Highlight wisely** - Only highlight important warnings
+4. **Keep concise** - Don't make values too long
+5. **Test layouts** - Verify display with different content lengths
+6. **Localize labels** - Translate labels for i18n
+7. **Match design system** - Use consistent spacing and colors
+
+## Styling
+
+```typescript
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    // Add vertical padding for spacing between rows
+    paddingVertical: 8,
+  },
+});
+```
+
+## Related Components
+
+- **PremiumDetailsCard** - Uses this component internally
+- **CreditRow** - Similar component for credit display
+- **SubscriptionSection** - Section containing detail rows
+
+## See Also
+
+- [Subscription Details](../../hooks/useSubscriptionDetails.md)
+- [Status Display](../../hooks/useSubscriptionStatus.md)