@umituz/react-native-design-system 2.6.94 → 2.6.96

package/src/molecules/StepProgress/README.md

@@ -1,522 +1,355 @@
 # StepProgress
 
-StepProgress, çok adımlı iş akışlarında ilerleme durumunu gösteren basit ve etkili bir bileşendir. Yatay ilerleme çubuğu ile hangi adımda olduğunuzu görselleştirir.
+A simple progress indicator for multi-step workflows that visualizes current step with a horizontal progress bar.
 
-## Özellikler
+## Import & Usage
 
-- 📊 **Görsel İlerleme**: Adım ilerlemesini görselleştirir
-- 🎨 **Tema Bilinci**: Design token uyumlu
-- 🎯 **Basit Kullanım**: Sadece 2 prop gerekli
-- ♿ **Erişilebilir**: Screen reader desteği
-- 📐 **Responsive**: Otomatik genişlik ayarı
+```typescript
+import { StepProgress } from 'react-native-design-system/src/molecules/StepProgress';
+```
+
+**Location:** `src/molecules/StepProgress/StepProgress.tsx`
 
-## Kurulum
+## Basic Usage
 
 ```tsx
-import { StepProgress } from 'react-native-design-system';
+<StepProgress
+  currentStep={2}
+  totalSteps={4}
+/>
 ```
 
-## Temel Kullanım
+## Strategy
 
-```tsx
-import React, { useState } from 'react';
-import { View } from 'react-native';
-import { StepProgress } from 'react-native-design-system';
-
-export const BasicExample = () => {
-  const [currentStep, setCurrentStep] = useState(2);
-  const totalSteps = 4;
-
-  return (
-    <View>
-      <StepProgress
-        currentStep={currentStep}
-        totalSteps={totalSteps}
-      />
-    </View>
-  );
-};
-```
+**Purpose**: Provide clear visual indication of progress in multi-step workflows.
+
+**When to Use**:
+- Multi-step forms (3-7 steps)
+- Onboarding flows
+- Checkout wizards
+- Questionnaires
+- Task completion tracking
+- Profile completion flows
+
+**When NOT to Use**:
+- For continuous progress (use ProgressBar instead)
+- For single-step forms
+- For too many steps (>7)
+- For non-sequential tasks
+
+## Rules
+
+### Required
+
+1. **MUST** provide `currentStep` and `totalSteps`
+2. **MUST** keep totalSteps between 3 and 7
+3. **ALWAYS** update currentStep dynamically
+4. **SHOULD** display step count to users
+5. **MUST** use 1-based indexing (currentStep starts at 1)
+6. **NEVER** show progress for single-step flows
+7. **ALWAYS** validate currentStep <= totalSteps
+
+### Step Management
+
+1. **currentStep**: 1-based index (starts at 1)
+2. **totalSteps**: Ideal 3-5, max 7
+3. **Update**: Increment/decrement based on navigation
+4. **Validation**: Ensure currentStep never exceeds totalSteps
+
+### Visual Guidelines
+
+1. **Position**: Above content, clearly visible
+2. **Size**: Full width of container
+3. **Color**: Theme primary color
+4. **Animation**: Smooth transitions between steps
 
-## Temel İlerleme
+### User Feedback
+
+1. **Show step number**: "Step 2 of 4"
+2. **Show percentage**: "50% complete"
+3. **Update immediately**: On step change
+4. **Indicate completion**: Special state when finished
+
+## Forbidden
+
+❌ **NEVER** do these:
 
 ```tsx
-{/* 3 adımdan 2. adım */}
+// ❌ Too many steps
 <StepProgress
-  currentStep={2}
-  totalSteps={3}
+  currentStep={5}
+  totalSteps={20} // ❌ Too many
 />
 
-{/* 5 adımdan 1. adım */}
+// ❌ Too few steps
 <StepProgress
   currentStep={1}
-  totalSteps={5}
+  totalSteps={2} // ❌ Too few for progress indicator
 />
-```
 
-## Dinamik İlerleme
+// ❌ Hardcoded currentStep
+<StepProgress
+  currentStep={2} // ❌ Not dynamic
+  totalSteps={4}
+/>
 
-```tsx
-export const DynamicProgress = () => {
-  const [step, setStep] = useState(1);
-  const totalSteps = 4;
-
-  return (
-    <View>
-      <StepProgress
-        currentStep={step}
-        totalSteps={totalSteps}
-      />
-
-      <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginTop: 16 }}>
-        <Button
-          title="Geri"
-          disabled={step === 1}
-          onPress={() => setStep(step - 1)}
-        />
-        <Button
-          title="İleri"
-          disabled={step === totalSteps}
-          onPress={() => setStep(step + 1)}
-        />
-      </View>
-    </View>
-  );
-};
-```
+// ❌ Wrong indexing (0-based)
+<StepProgress
+  currentStep={1} // ❌ Should be 2 for second step
+  totalSteps={4}
+/>
 
-## Örnek Kullanımlar
+// ❌ currentStep exceeds totalSteps
+<StepProgress
+  currentStep={5} // ❌ Exceeds totalSteps
+  totalSteps={4}
+/>
 
-### Onboarding Flow
+// ❌ Negative or zero steps
+<StepProgress
+  currentStep={0} // ❌ Should be 1-based
+  totalSteps={4}
+/>
 
-```tsx
-export const OnboardingProgress = () => {
-  const [currentStep, setCurrentStep] = useState(1);
-  const steps = [
-    { id: 1, title: 'Hoş Geldiniz' },
-    { id: 2, title: 'Profil' },
-    { id: 3, title: 'İlgi Alanları' },
-    { id: 4, title: 'Bitir' },
-  ];
-
-  return (
-    <ScreenLayout>
-      <StepProgress
-        currentStep={currentStep}
-        totalSteps={steps.length}
-      />
-
-      <View style={{ flex: 1, justifyContent: 'center' }}>
-        <AtomicText type="headlineLarge" style={{ textAlign: 'center' }}>
-          {steps[currentStep - 1].title}
-        </AtomicText>
-      </View>
-
-      <View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
-        <Button
-          title="Geri"
-          disabled={currentStep === 1}
-          onPress={() => setCurrentStep(currentStep - 1)}
-        />
-        <Button
-          title={currentStep === steps.length ? 'Bitir' : 'İleri'}
-          onPress={() => {
-            if (currentStep < steps.length) {
-              setCurrentStep(currentStep + 1);
-            } else {
-              // Finish
-            }
-          }}
-        />
-      </View>
-    </ScreenLayout>
-  );
-};
+// ❌ Missing progress display
+<View>
+  <StepProgress currentStep={2} totalSteps={4} />
+  {/* ❌ No indication of which step */}
+</View>
 ```
 
-### Checkout Süreci
+## Best Practices
+
+### Dynamic Step Management
 
+✅ **DO**:
 ```tsx
-export const CheckoutProgress = () => {
-  const [checkoutStep, setCheckoutStep] = useState(1);
-  const checkoutSteps = ['Sepet', 'Teslimat', 'Ödeme', 'Onay'];
-
-  return (
-    <View>
-      <StepProgress
-        currentStep={checkoutStep}
-        totalSteps={checkoutSteps.length}
-      />
-
-      <View style={{ marginTop: 16 }}>
-        <AtomicText type="titleMedium" style={{ textAlign: 'center', marginBottom: 8 }}>
-          {checkoutSteps[checkoutStep - 1]}
-        </AtomicText>
-      </View>
-
-      {/* Step content */}
-    </View>
-  );
-};
-```
+const [step, setStep] = useState(1);
 
-### Quiz İlerlemesi
+<View>
+  <StepProgress
+    currentStep={step}
+    totalSteps={4}
+  />
+  <AtomicText>Step {step} of 4</AtomicText>
+  <Button
+    title="Next"
+    onPress={() => setStep(Math.min(step + 1, 4))}
+  />
+</View>
+```
 
+❌ **DON'T**:
 ```tsx
-export const QuizProgress = () => {
-  const [questionIndex, setQuestionIndex] = useState(0);
-  const questions = [
-    'Soru 1',
-    'Soru 2',
-    'Soru 3',
-    'Soru 4',
-    'Soru 5',
-  ];
-
-  const progress = questionIndex + 1;
-
-  return (
-    <View>
-      <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginBottom: 8 }}>
-        <AtomicText type="labelLarge">Soru {progress}/{questions.length}</AtomicText>
-        <AtomicText type="labelLarge" color="primary">
-          %{Math.round((progress / questions.length) * 100)}
-        </AtomicText>
-      </View>
-
-      <StepProgress
-        currentStep={progress}
-        totalSteps={questions.length}
-      />
-
-      <View style={{ marginTop: 24 }}>
-        <AtomicText type="headlineMedium">{questions[questionIndex]}</AtomicText>
-      </View>
-
-      <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginTop: 32 }}>
-        <Button
-          title="Önceki"
-          disabled={questionIndex === 0}
-          onPress={() => setQuestionIndex(questionIndex - 1)}
-        />
-        <Button
-          title={questionIndex === questions.length - 1 ? 'Bitir' : 'Sonraki'}
-          onPress={() => {
-            if (questionIndex < questions.length - 1) {
-              setQuestionIndex(questionIndex + 1);
-            } else {
-              // Submit quiz
-            }
-          }}
-        />
-      </View>
-    </View>
-  );
-};
+// ❌ Hardcoded
+<StepProgress
+  currentStep={2}
+  totalSteps={4}
+/>
 ```
 
-### Form Adımları
+### Number of Steps
 
+✅ **DO**:
 ```tsx
-export const FormWizard = () => {
-  const [formStep, setFormStep] = useState(1);
-  const formSteps = ['Kişisel', 'İletişim', 'Adres', 'Onay'];
-
-  return (
-    <AtomicCard variant="outlined">
-      <View style={{ padding: 16 }}>
-        <StepProgress
-          currentStep={formStep}
-          totalSteps={formSteps.length}
-        />
-
-        <View style={{ marginTop: 24 }}>
-          {formStep === 1 && (
-            <View>
-              <AtomicText type="titleLarge">Kişisel Bilgiler</AtomicText>
-              <FormField label="Ad" />
-              <FormField label="Soyad" />
-            </View>
-          )}
-
-          {formStep === 2 && (
-            <View>
-              <AtomicText type="titleLarge">İletişim Bilgileri</AtomicText>
-              <FormField label="E-posta" />
-              <FormField label="Telefon" />
-            </View>
-          )}
-
-          {formStep === 3 && (
-            <View>
-              <AtomicText type="titleLarge">Adres</AtomicText>
-              <FormField label="Şehir" />
-              <FormField label="Ülke" />
-            </View>
-          )}
-
-          {formStep === 4 && (
-            <View>
-              <AtomicText type="titleLarge">Onayla</AtomicText>
-              <AtomicText>Bilgilerinizi kontrol edin</AtomicText>
-            </View>
-          )}
-        </View>
-
-        <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginTop: 24 }}>
-          <Button
-            title="Geri"
-            variant="ghost"
-            disabled={formStep === 1}
-            onPress={() => setFormStep(formStep - 1)}
-          />
-          <Button
-            title={formStep === formSteps.length ? 'Gönder' : 'İleri'}
-            onPress={() => {
-              if (formStep < formSteps.length) {
-                setFormStep(formStep + 1);
-              } else {
-                // Submit form
-              }
-            }}
-          />
-        </View>
-      </View>
-    </AtomicCard>
-  );
-};
+// ✅ Good: 3-5 steps
+<StepProgress currentStep={2} totalSteps={4} />
 ```
 
-### Görev İzleme
-
+❌ **DON'T**:
 ```tsx
-export const TaskTracker = () => {
-  const [completedTasks, setCompletedTasks] = useState(0);
-  const totalTasks = 10;
-
-  const toggleTask = () => {
-    if (completedTasks < totalTasks) {
-      setCompletedTasks(completedTasks + 1);
-    }
-  };
-
-  const progressPercentage = Math.round((completedTasks / totalTasks) * 100);
-
-  return (
-    <AtomicCard variant="elevated">
-      <View style={{ padding: 16 }}>
-        <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginBottom: 8 }}>
-          <AtomicText type="titleMedium">Günlük Görevler</AtomicText>
-          <AtomicText type="labelLarge" color="primary">
-            %{progressPercentage}
-          </AtomicText>
-        </View>
-
-        <StepProgress
-          currentStep={completedTasks}
-          totalTasks={totalTasks}
-        />
-
-        <View style={{ marginTop: 16 }}>
-          <AtomicText type="bodyMedium" color="secondary">
-            {completedTasks}/{totalTasks} görev tamamlandı
-          </AtomicText>
-        </View>
-
-        {completedTasks < totalTasks && (
-          <Button
-            title="Görevi Tamamla"
-            onPress={toggleTask}
-            style={{ marginTop: 16 }}
-          />
-        )}
-
-        {completedTasks === totalTasks && (
-          <View style={{ marginTop: 16, alignItems: 'center' }}>
-            <AtomicIcon name="checkmark-circle" size="xl" color="success" />
-            <AtomicText type="titleMedium" color="success" style={{ marginTop: 8 }}>
-              Tüm görevler tamamlandı!
-            </AtomicText>
-          </View>
-        )}
-      </View>
-    </AtomicCard>
-  );
-};
+// ❌ Bad: Too many
+<StepProgress currentStep={5} totalSteps={15} />
+
+// ❌ Bad: Too few
+<StepProgress currentStep={1} totalSteps={2} />
 ```
 
-### Dosya Yükleme İlerlemesi
+### User Feedback
 
+✅ **DO**:
 ```tsx
-export const FileUploadProgress = () => {
-  const [uploadedFiles, setUploadedFiles] = useState(0);
-  const totalFiles = 5;
-
-  const uploadFile = () => {
-    if (uploadedFiles < totalFiles) {
-      setUploadedFiles(uploadedFiles + 1);
-    }
-  };
-
-  return (
-    <View>
-      <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginBottom: 8 }}>
-        <AtomicText type="titleMedium">Dosya Yükleme</AtomicText>
-        <AtomicText type="labelLarge">
-          {uploadedFiles}/{totalFiles}
-        </AtomicText>
-      </View>
-
-      <StepProgress
-        currentStep={uploadedFiles}
-        totalSteps={totalFiles}
-      />
-
-      {uploadedFiles < totalFiles && (
-        <Button
-          title="Dosya Yükle"
-          onPress={uploadFile}
-          style={{ marginTop: 16 }}
-        />
-      )}
-
-      {uploadedFiles === totalFiles && (
-        <AtomicText type="bodyMedium" color="success" style={{ marginTop: 16 }}>
-          Tüm dosyalar yüklendi ✓
-        </AtomicText>
-      )}
-    </View>
-  );
-};
+<View>
+  <View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
+    <AtomicText>Question {currentStep}/{totalSteps}</AtomicText>
+    <AtomicText>%{Math.round((currentStep / totalSteps) * 100)}</AtomicText>
+  </View>
+  <StepProgress currentStep={currentStep} totalSteps={totalSteps} />
+</View>
 ```
 
-### Profil Tamamlama
+### Step Validation
 
+✅ **DO**:
 ```tsx
-export const ProfileCompletion = () => {
-  const [completedSections, setCompletedSections] = useState(2);
-  const totalSections = 5;
-
-  const sections = [
-    { id: 1, name: 'Profil Fotoğrafı', completed: true },
-    { id: 2, name: 'Kişisel Bilgiler', completed: true },
-    { id: 3, name: 'İletişim Bilgileri', completed: false },
-    { id: 4, name: 'Eğitim', completed: false },
-    { id: 5, name: 'Deneyim', completed: false },
-  ];
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicText type="headlineMedium" style={{ marginBottom: 8 }}>
-        Profilinizi Tamamlayın
-      </AtomicText>
-
-      <StepProgress
-        currentStep={completedSections}
-        totalSteps={totalSections}
-      />
-
-      <View style={{ marginTop: 16 }}>
-        <AtomicText type="bodyMedium" color="secondary">
-          {completedSections}/{totalSections} bölüm tamamlandı
-        </AtomicText>
-      </View>
-
-      <View style={{ marginTop: 16 }}>
-        {sections.map((section) => (
-          <View
-            key={section.id}
-            style={{
-              flexDirection: 'row',
-              alignItems: 'center',
-              paddingVertical: 8,
-              borderBottomWidth: 1,
-              borderBottomColor: '#e0e0e0',
-            }}
-          >
-            <AtomicIcon
-              name={section.completed ? 'checkmark-circle' : 'ellipse-outline'}
-              size="md"
-              color={section.completed ? 'success' : 'secondary'}
-            />
-            <AtomicText style={{ marginLeft: 12 }}>
-              {section.name}
-            </AtomicText>
-          </View>
-        ))}
-      </View>
-    </View>
-  );
+const goToNextStep = () => {
+  if (currentStep < totalSteps) {
+    setCurrentStep(currentStep + 1);
+  }
+};
+
+const goToPrevStep = () => {
+  if (currentStep > 1) {
+    setCurrentStep(currentStep - 1);
+  }
 };
 ```
 
-## Props
+## AI Coding Guidelines
 
-### StepProgressProps
+### For AI Agents
 
-| Prop | Tip | Varsayılan | Açıklama |
-|------|-----|------------|----------|
-| `currentStep` | `number` | - **(Zorunlu)** | Mevcut adım |
-| `totalSteps` | `number` | - **(Zorunlu)** | Toplam adım sayısı |
-| `style` | `ViewStyle` | - | Özel stil |
+When generating StepProgress components, follow these rules:
 
-## Best Practices
+1. **Always import from correct path**:
+   ```typescript
+   import { StepProgress } from 'react-native-design-system/src/molecules/StepProgress';
+   ```
 
-### 1. Adım Sayısı
+2. **Always use dynamic state management**:
+   ```tsx
+   // ✅ Good - dynamic state
+   const [step, setStep] = useState(1);
+   <StepProgress currentStep={step} totalSteps={4} />
 
-```tsx
-// İdeal: 3-7 adım
-<StepProgress currentStep={2} totalSteps={5} /> // ✅
+   // ❌ Bad - hardcoded
+   <StepProgress currentStep={2} totalSteps={4} />
+   ```
 
-// Çok az
-<StepProgress currentStep={1} totalSteps={2} /> // ⚠️
+3. **Always validate step count**:
+   ```tsx
+   // ✅ Good - appropriate number of steps
+   <StepProgress currentStep={2} totalSteps={4} />
 
-// Çok fazla
-<StepProgress currentStep={5} totalSteps={20} /> // ❌
-```
+   // ❌ Bad - too many steps
+   <StepProgress currentStep={5} totalSteps={20} />
+   ```
 
-### 2. State Yönetimi
+4. **Always provide user feedback**:
+   ```tsx
+   // ✅ Good - show step number
+   <View>
+     <AtomicText>Step {step} of {totalSteps}</AtomicText>
+     <StepProgress currentStep={step} totalSteps={totalSteps} />
+   </View>
 
-```tsx
-// Doğru
-const [step, setStep] = useState(1);
-<StepProgress currentStep={step} totalSteps={5} />
+   // ❌ Bad - no feedback
+   <StepProgress currentStep={step} totalSteps={totalSteps} />
+   ```
 
-// Yanlış (hardcoded)
-<StepProgress currentStep={2} totalSteps={5} /> // ❌
-```
+5. **Always use 1-based indexing**:
+   ```tsx
+   // ✅ Good - 1-based
+   const [step, setStep] = useState(1); // Starts at 1
+
+   // ❌ Bad - 0-based
+   const [step, setStep] = useState(0); // Starts at 0
+   ```
 
-### 3. Kullanıcı Geri Bildirimi
+### Common Patterns
+
+#### Onboarding Progress
+```tsx
+const [currentStep, setCurrentStep] = useState(1);
+const steps = ['Welcome', 'Profile', 'Interests', 'Finish'];
+
+<View>
+  <StepProgress
+    currentStep={currentStep}
+    totalSteps={steps.length}
+  />
+  <AtomicText type="titleMedium" style={{ textAlign: 'center', marginTop: 8 }}>
+    {steps[currentStep - 1]}
+  </AtomicText>
+  <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginTop: 16 }}>
+    <Button
+      title="Back"
+      disabled={currentStep === 1}
+      onPress={() => setCurrentStep(currentStep - 1)}
+    />
+    <Button
+      title={currentStep === steps.length ? 'Finish' : 'Next'}
+      onPress={() => setCurrentStep(Math.min(currentStep + 1, steps.length))}
+    />
+  </View>
+</View>
+```
 
+#### Quiz Progress
 ```tsx
-// Adım numarasını göster
-<AtomicText>Adım {currentStep}/{totalSteps}</AtomicText>
+const [questionIndex, setQuestionIndex] = useState(0);
+const questions = ['Q1', 'Q2', 'Q3', 'Q4', 'Q5'];
+
+<View>
+  <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginBottom: 8 }}>
+    <AtomicText type="labelLarge">
+      Question {questionIndex + 1}/{questions.length}
+    </AtomicText>
+    <AtomicText type="labelLarge" color="primary">
+      %{Math.round(((questionIndex + 1) / questions.length) * 100)}
+    </AtomicText>
+  </View>
+  <StepProgress
+    currentStep={questionIndex + 1}
+    totalSteps={questions.length}
+  />
+  <AtomicText type="headlineMedium" style={{ marginTop: 24 }}>
+    {questions[questionIndex]}
+  </AtomicText>
+</View>
+```
 
-// Yüzde göster
-<AtomicText>%{Math.round((currentStep / totalSteps) * 100)}</AtomicText>
+#### Task Completion
+```tsx
+const [completedTasks, setCompletedTasks] = useState(0);
+const totalTasks = 10;
+
+<View>
+  <View style={{ flexDirection: 'row', justifyContent: 'space-between', marginBottom: 8 }}>
+    <AtomicText type="titleMedium">Daily Tasks</AtomicText>
+    <AtomicText type="labelLarge" color="primary">
+      %{Math.round((completedTasks / totalTasks) * 100)}
+    </AtomicText>
+  </View>
+  <StepProgress
+    currentStep={completedTasks}
+    totalSteps={totalTasks}
+  />
+  <AtomicText type="bodyMedium" color="secondary" style={{ marginTop: 8 }}>
+    {completedTasks}/{totalTasks} tasks completed
+  </AtomicText>
+</View>
 ```
 
-## Erişilebilirlik
+## Props Reference
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `currentStep` | `number` | **Yes** | - | Current step (1-based) |
+| `totalSteps` | `number` | **Yes** | - | Total number of steps (3-7 recommended) |
+| `style` | `ViewStyle` | No | - | Custom container style |
 
-StepProgress, tam erişilebilirlik desteği sunar:
+## Accessibility
 
-- ✅ Screen reader desteği
-- ✅ Semantic role
-- ✅ Progress anonsu
-- ✅ Görsel kontrast
+- ✅ Screen reader announces progress
+- ✅ Semantic progress role
+- ✅ Visual contrast maintained
+- ✅ Progress percentage available
+- ✅ Step count announced
 
-## Performans İpuçları
+## Performance Tips
 
-1. **Memoization**: Component'i memo edin
-2. **Minimal Props**: Sadece gerekli props'ları kullanın
-3. **Stable References**: Callback'leri useCallback ile sarın
+1. **Memoization**: Memo component to prevent re-renders
+2. **Minimal props**: Only 2 required props
+3. **Stable references**: Use stable state values
+4. **Optimize updates**: Only update when step changes
 
-## İlgili Bileşenler
+## Related Components
 
-- [`StepHeader`](../StepHeader/README.md) - Adım başlığı
-- [`Divider`](../Divider/README.md) - Ayırıcı
-- [`AtomicText`](../../atoms/AtomicText/README.md) - Metin bileşeni
+- [`StepHeader`](../StepHeader/README.md) - Step header component
+- [`Divider`](../Divider/README.md) - Divider component
+- [`AtomicText`](../../atoms/AtomicText/README.md) - Text component
 
-## Lisans
+## License
 
 MIT