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

package/src/molecules/StepHeader/README.md

@@ -1,487 +1,387 @@
 # StepHeader
 
-StepHeader, adım adım ilerleyen iş akışları (onboarding, kayıt, wizard vb.) için kullanılan başlık bileşenidir. Adım göstergesi, başlık ve alt başlık içerir.
+A header component for step-by-step workflows (onboarding, registration, wizard) with step indicator, title, and subtitle.
 
-## Özellikler
+## Import & Usage
 
-- 📊 **Step Indicator**: Adım göstergesi (dot sistemi)
-- 📝 **Title & Subtitle**: Başlık ve açıklama metni
-- 🎯 **Hizalama**: Sol, orta, sağ hizalama seçenekleri
-- 🎨 **Özelleştirilebilir**: Font boyutu, boşluk ayarları
-- 🎭 **Tema Bilinci**: Design token uyumlu
-- ♿ **Erişilebilir**: Screen reader desteği
-
-## Kurulum
-
-```tsx
-import { StepHeader } from 'react-native-design-system';
+```typescript
+import { StepHeader } from 'react-native-design-system/src/molecules/StepHeader';
 ```
 
-## Temel Kullanım
-
-```tsx
-import React from 'react';
-import { View } from 'react-native';
-import { StepHeader } from 'react-native-design-system';
-
-export const BasicExample = () => {
-  return (
-    <View>
-      <StepHeader
-        title="Hoş Geldiniz"
-        subtitle="Hesabınızı oluşturmak için birkaç adım"
-      />
-    </View>
-  );
-};
-```
+**Location:** `src/molecules/StepHeader/StepHeader.tsx`
 
-## Step Indicator ile
+## Basic Usage
 
 ```tsx
 <StepHeader
-  title="Profil Bilgileri"
-  subtitle="Lütfen kişisel bilgilerinizi girin"
+  title="Welcome"
+  subtitle="A few steps to create your account"
   config={{
     showStepIndicator: true,
-    currentStep: 2,
+    currentStep: 1,
     totalSteps: 4,
   }}
 />
 ```
 
-## Adım Göstergesi
+## Strategy
 
-```tsx
-<View>
-  {/* 1. Adım */}
-  <StepHeader
-    title="Adım 1"
-    config={{
-      showStepIndicator: true,
-      currentStep: 1,
-      totalSteps: 3,
-    }}
-  />
-
-  {/* 2. Adım */}
-  <StepHeader
-    title="Adım 2"
-    config={{
-      showStepIndicator: true,
-      currentStep: 2,
-      totalSteps: 3,
-    }}
-  />
-
-  {/* 3. Adım */}
-  <StepHeader
-    title="Adım 3"
-    config={{
-      showStepIndicator: true,
-      currentStep: 3,
-      totalSteps: 3,
-    }}
-  />
-</View>
-```
+**Purpose**: Provide clear visual hierarchy and progress indication for multi-step workflows.
 
-## Hizalama Seçenekleri
+**When to Use**:
+- Onboarding flows (3-5 steps)
+- Registration forms (multi-step)
+- Checkout wizards
+- Setup assistants
+- Questionnaires/surveys
+- Profile completion flows
 
-```tsx
-<View>
-  {/* Sol hizalı (varsayılan) */}
-  <StepHeader
-    title="Sol Hizalı"
-    subtitle="Solaya hizalı başlık"
-    config={{
-      titleAlignment: 'left',
-    }}
-  />
-
-  {/* Ortalanmış */}
-  <StepHeader
-    title="Ortada"
-    subtitle="Ortalanmış başlık"
-    config={{
-      titleAlignment: 'center',
-    }}
-  />
-
-  {/* Sağ hizalı */}
-  <StepHeader
-    title="Sağ Hizalı"
-    subtitle="Sağa hizalı başlık"
-    config={{
-      titleAlignment: 'right',
-    }}
-  />
-</View>
-```
+**When NOT to Use**:
+- For single-step forms (use simple headers)
+- For long workflows (>7 steps, break into sections)
+- For non-sequential tasks
+- For simple pages (use PageHeader instead)
+
+## Rules
+
+### Required
+
+1. **MUST** provide a `title` prop
+2. **SHOULD** provide `subtitle` for context
+3. **MUST** keep title concise (1-2 lines max)
+4. **ALWAYS** show step indicator for multi-step workflows
+5. **SHOULD** use appropriate alignment (left for forms, center for onboarding)
+6. **MUST** have currentStep and totalSteps when showing indicator
+7. **NEVER** use too many steps (>7 is too many)
+
+### Step Indicator
 
-## Custom Font Boyutu
+1. **Show when**: 3+ steps in workflow
+2. **Position**: Above title, centered or aligned
+3. **Format**: Dot system (filled for completed, outlined for current)
+4. **Visibility**: Always visible, don't hide on last step
+
+### Content Guidelines
+
+1. **Title**: Clear, action-oriented (e.g., "Create Account" not "Step 1")
+2. **Subtitle**: Additional context, max 1 line
+3. **Number of steps**: Ideal 3-5, max 7
+4. **Alignment**: Left for forms, center for onboarding
+
+### Spacing & Layout
+
+1. **Margin bottom**: 32px default
+2. **Padding horizontal**: 24px default
+3. **Font size**: Title 28px, subtitle 16px default
+4. **Responsive**: Adjust sizing for different screens
+
+## Forbidden
+
+❌ **NEVER** do these:
 
 ```tsx
+// ❌ No title
+<StepHeader
+  // Missing title
+  subtitle="This has no title"
+/>
+
+// ❌ Too many steps
 <StepHeader
-  title="Büyük Başlık"
-  subtitle="Alt başlık"
+  title="Step 1"
   config={{
-    titleFontSize: 32,
-    subtitleFontSize: 18,
+    showStepIndicator: true,
+    currentStep: 1,
+    totalSteps: 15, // ❌ Too many steps
   }}
 />
-```
 
-## Custom Boşluk
+// ❌ Title too long
+<StepHeader
+  title="Please enter your personal profile information including your name email address phone number and physical address" // ❌ Too long
+  subtitle="Required information"
+/>
 
-```tsx
+// ❌ Step indicator without totalSteps
 <StepHeader
-  title="Özel Boşluk"
-  subtitle="Özel padding ve margin"
+  title="Step 1"
   config={{
-    spacing: {
-      marginBottom: 48,
-      paddingHorizontal: 32,
-    },
+    showStepIndicator: true,
+    currentStep: 1,
+    // Missing totalSteps
+  }}
+/>
+
+// ❌ Wrong alignment for RTL
+<StepHeader
+  title="مرحبا" // Arabic text
+  config={{
+    titleAlignment: 'left', // ❌ Should be right for RTL
+  }}
+/>
+
+// ❌ Generic titles
+<StepHeader
+  title="Step 1" // ❌ Not descriptive
+  config={{
+    showStepIndicator: true,
+    currentStep: 1,
+    totalSteps: 3,
   }}
 />
 ```
 
-## Örnek Kullanımlar
+## Best Practices
 
 ### Onboarding Flow
 
+✅ **DO**:
 ```tsx
-export const OnboardingFlow = () => {
-  const [currentStep, setCurrentStep] = useState(1);
-  const steps = [
-    {
-      title: 'Hoş Geldiniz 👋',
-      subtitle: 'Uygulamamıza hoş geldiniz',
-    },
-    {
-      title: 'Profil Oluştur',
-      subtitle: 'Kendiniz hakkında bilgi verin',
-    },
-    {
-      title: 'İlgi Alanları',
-      subtitle: 'İlgi alanlarınızı seçin',
-    },
-    {
-      title: 'Hazır! 🎉',
-      subtitle: 'Uygulamayı kullanmaya başlayın',
-    },
-  ];
-
-  const currentStepData = steps[currentStep - 1];
-
-  return (
-    <ScreenLayout>
-      <StepHeader
-        title={currentStepData.title}
-        subtitle={currentStepData.subtitle}
-        config={{
-          showStepIndicator: true,
-          currentStep,
-          totalSteps: steps.length,
-          titleAlignment: 'center',
-        }}
-      />
-
-      {/* Step content */}
-
-      <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 onboarding
-            }
-          }}
-        />
-      </View>
-    </ScreenLayout>
-  );
-};
+<StepHeader
+  title="Welcome 👋"
+  subtitle="Let's get you set up"
+  config={{
+    showStepIndicator: true,
+    currentStep: 1,
+    totalSteps: 4,
+    titleAlignment: 'center',
+  }}
+/>
 ```
 
-### Kayıt Formu
-
+❌ **DON'T**:
 ```tsx
-export const RegistrationForm = () => {
-  const [step, setStep] = useState(1);
-
-  return (
-    <ScreenLayout>
-      {step === 1 && (
-        <>
-          <StepHeader
-            title="Hesap Oluştur"
-            subtitle="E-posta adresiniz ve şifreniz ile başlayın"
-            config={{
-              showStepIndicator: true,
-              currentStep: 1,
-              totalSteps: 3,
-            }}
-          />
-          {/* Email & password fields */}
-        </>
-      )}
-
-      {step === 2 && (
-        <>
-          <StepHeader
-            title="Profil Bilgileri"
-            subtitle="Adınızı ve profil fotoğrafınızı ekleyin"
-            config={{
-              showStepIndicator: true,
-              currentStep: 2,
-              totalSteps: 3,
-            }}
-          />
-          {/* Profile fields */}
-        </>
-      )}
-
-      {step === 3 && (
-        <>
-          <StepHeader
-            title="Onayla"
-            subtitle="Bilgilerinizi kontrol edin"
-            config={{
-              showStepIndicator: true,
-              currentStep: 3,
-              totalSteps: 3,
-            }}
-          />
-          {/* Confirmation */}
-        </>
-      )}
-    </ScreenLayout>
-  );
-};
+// ❌ Generic step title
+<StepHeader
+  title="Step 1"
+  config={{
+    showStepIndicator: true,
+    currentStep: 1,
+    totalSteps: 4,
+  }}
+/>
 ```
 
-### Checkout Wizard
+### Registration Form
 
+✅ **DO**:
 ```tsx
-export const CheckoutWizard = () => {
-  const [currentStep, setCurrentStep] = useState(1);
-
-  const steps = [
-    { id: 1, title: 'Teslimat', subtitle: 'Teslimat adresini seçin' },
-    { id: 2, title: 'Ödeme', subtitle: 'Ödeme yöntemini seçin' },
-    { id: 3, title: 'Onay', subtitle: 'Siparişi onaylayın' },
-  ];
-
-  return (
-    <ScreenLayout>
-      <StepHeader
-        title={steps[currentStep - 1].title}
-        subtitle={steps[currentStep - 1].subtitle}
-        config={{
-          showStepIndicator: true,
-          currentStep,
-          totalSteps: steps.length,
-        }}
-      />
-
-      {/* Step content */}
-    </ScreenLayout>
-  );
-};
+<StepHeader
+  title="Create Account"
+  subtitle="Start with your email and password"
+  config={{
+    showStepIndicator: true,
+    currentStep: 1,
+    totalSteps: 3,
+    titleAlignment: 'left',
+  }}
+/>
 ```
 
-### Profil Tamamlama
+### Number of Steps
 
+✅ **DO**:
 ```tsx
-export const ProfileCompletion = ({ completionPercentage }) => {
-  const totalSteps = 5;
-  const currentStep = Math.ceil((completionPercentage / 100) * totalSteps);
-
-  return (
-    <View>
-      <StepHeader
-        title="Profilinizi Tamamlayın"
-        subtitle={`${completionPercentage}% tamamlandı`}
-        config={{
-          showStepIndicator: true,
-          currentStep,
-          totalSteps,
-          titleAlignment: 'center',
-        }}
-      />
-    </View>
-  );
-};
+// ✅ Good: 3-5 steps
+totalSteps: 4
 ```
 
-### Setup Assistant
-
+❌ **DON'T**:
 ```tsx
-export const SetupAssistant = () => {
-  const [setupStep, setSetupStep] = useState(1);
-
-  const setupSteps = [
-    { title: 'Dil Seçin', subtitle: 'Tercih ettiğiniz dili seçin' },
-    { title: 'Bildirimler', subtitle: 'Bildirim tercihlerinizi ayarlayın' },
-    { title: 'Gizlilik', subtitle: 'Gizlilik ayarlarınızı yapılandırın' },
-    { title: 'Tema', subtitle: 'Uygulama temasını özelleştirin' },
-  ];
-
-  return (
-    <ScreenLayout>
-      <StepHeader
-        title={setupSteps[setupStep - 1].title}
-        subtitle={setupSteps[setupStep - 1].subtitle}
-        config={{
-          showStepIndicator: true,
-          currentStep: setupStep,
-          totalSteps: setupSteps.length,
-          titleFontSize: 24,
-          subtitleFontSize: 14,
-        }}
-      />
-
-      {/* Setup content */}
-    </ScreenLayout>
-  );
-};
+// ❌ Bad: Too many steps
+totalSteps: 10
+
+// ❌ Bad: Too few for indicator
+totalSteps: 2
 ```
 
-### Questionnaire
+### Title Length
 
+✅ **DO**:
 ```tsx
-export const Questionnaire = () => {
-  const [questionIndex, setQuestionIndex] = useState(0);
-  const questions = [
-    { title: 'Soru 1', subtitle: 'Yaşınız nedir?' },
-    { title: 'Soru 2', subtitle: 'Mesleğiniz nedir?' },
-    { title: 'Soru 3', subtitle: 'İlgi alanlarınız nelerdir?' },
-  ];
-
-  return (
-    <View>
-      <StepHeader
-        title={questions[questionIndex].title}
-        subtitle={questions[questionIndex].subtitle}
-        config={{
-          showStepIndicator: true,
-          currentStep: questionIndex + 1,
-          totalSteps: questions.length,
-          titleAlignment: 'center',
-          spacing: {
-            marginBottom: 24,
-            paddingHorizontal: 16,
-          },
-        }}
-      />
-
-      {/* Question content */}
-    </View>
-  );
-};
+// ✅ Good: Concise and clear
+title="Create Profile"
+title="Enter Your Details"
+title="Almost Done!"
 ```
 
-## Props
-
-### StepHeaderProps
-
-| Prop | Tip | Varsayılan | Açıklama |
-|------|-----|------------|----------|
-| `title` | `string` | - **(Zorunlu)** | Ana başlık |
-| `subtitle` | `string` | - | Alt başlık |
-| `config` | `StepHeaderConfig` | `{}` | Konfigürasyon |
-| `style` | `ViewStyle` | - | Özel stil |
-
-### StepHeaderConfig
-
-| Prop | Tip | Varsayılan | Açıklama |
-|------|-----|------------|----------|
-| `showStepIndicator` | `boolean` | `false` | Adım göstergesi göster |
-| `currentStep` | `number` | - | Mevcut adım |
-| `totalSteps` | `number` | - | Toplam adım sayısı |
-| `titleAlignment` | `'left' \| 'center' \| 'right'` | `'left'` | Başlık hizalaması |
-| `titleFontSize` | `number` | `28` | Başlık font boyutu |
-| `subtitleFontSize` | `number` | `16` | Alt başlık font boyutu |
-| `spacing` | `object` | - | Boşluk ayarları |
-| `spacing.marginBottom` | `number` | `32` | Alt boşluk |
-| `spacing.paddingHorizontal` | `number` | `24` | Yatay boşluk |
-
-## Best Practices
-
-### 1. Step Indicator Kullanımı
-
+❌ **DON'T**:
 ```tsx
-// Çok adımlı iş akışlarında
-config={{
-  showStepIndicator: true,
-  currentStep: 2,
-  totalSteps: 5,
-}}
+// ❌ Bad: Too long
+title="Please Enter Your Personal Profile Information Here"
 ```
 
-### 2. Hizalama Seçimi
-
+## AI Coding Guidelines
+
+### For AI Agents
+
+When generating StepHeader components, follow these rules:
+
+1. **Always import from correct path**:
+   ```typescript
+   import { StepHeader } from 'react-native-design-system/src/molecules/StepHeader';
+   ```
+
+2. **Always provide a title**:
+   ```tsx
+   // ✅ Good
+   <StepHeader
+     title="创建账户"
+     subtitle="输入您的电子邮件和密码"
+     config={{
+       showStepIndicator: true,
+       currentStep: step,
+       totalSteps: totalSteps,
+     }}
+   />
+
+   // ❌ Bad - no title
+   <StepHeader
+     subtitle="No title provided"
+   />
+   ```
+
+3. **Always use descriptive titles, not step numbers**:
+   ```tsx
+   // ✅ Good - descriptive
+   title="Create Account"
+   title="Enter Profile Information"
+   title="Review and Confirm"
+
+   // ❌ Bad - generic
+   title="Step 1"
+   title="Step 2"
+   title="Step 3"
+   ```
+
+4. **Always show step indicator for multi-step workflows**:
+   ```tsx
+   // ✅ Good - with indicator
+   <StepHeader
+     title="Profile Information"
+     config={{
+       showStepIndicator: true,
+       currentStep: 2,
+       totalSteps: 4,
+     }}
+   />
+
+   // ❌ Bad - no indicator in multi-step flow
+   <StepHeader
+     title="Profile Information"
+     // Missing step indicator
+   />
+   ```
+
+5. **Always choose appropriate alignment**:
+   ```tsx
+   // ✅ Good - left for forms
+   config={{
+     titleAlignment: 'left',
+   }}
+
+   // ✅ Good - center for onboarding
+   config={{
+     titleAlignment: 'center',
+   }}
+
+   // ✅ Good - right for RTL languages
+   config={{
+     titleAlignment: 'right',
+   }}
+   ```
+
+### Common Patterns
+
+#### Onboarding Step Header
 ```tsx
-// Form için
-titleAlignment: 'left'
-
-// Onboarding için
-titleAlignment: 'center'
-
-// RTL diller için
-titleAlignment: 'right'
+<StepHeader
+  title="Welcome 👋"
+  subtitle="Let's get you set up in a few steps"
+  config={{
+    showStepIndicator: true,
+    currentStep: 1,
+    totalSteps: 4,
+    titleAlignment: 'center',
+    spacing: {
+      marginBottom: 48,
+    },
+  }}
+/>
 ```
 
-### 3. Adım Sayısı
-
+#### Registration Form Step Header
 ```tsx
-// İdeal: 3-5 adım
-totalSteps: 4
-
-// Çok fazla adımdan kaçının
-totalSteps: 10 // ❌ Kötü
+<StepHeader
+  title="Personal Information"
+  subtitle="Tell us a bit about yourself"
+  config={{
+    showStepIndicator: true,
+    currentStep: 2,
+    totalSteps: 3,
+    titleAlignment: 'left',
+  }}
+/>
 ```
 
-### 4. Başlık Uzunluğu
-
+#### Checkout Step Header
 ```tsx
-// Kısa ve öz
-title="Profil Oluştur" // ✅ İyi
-
-// Çok uzun
-title="Lütfen kişisel profil bilgilerinizi buraya girin" // ❌ Kötü
+<StepHeader
+  title="Payment Method"
+  subtitle="Choose how you want to pay"
+  config={{
+    showStepIndicator: true,
+    currentStep: 3,
+    totalSteps: 4,
+  }}
+/>
 ```
 
-## Erişilebilirlik
-
-StepHeader, tam erişilebilirlik desteği sunar:
-
-- ✅ Screen reader desteği
-- ✅ Semantic heading yapısı
-- ✅ Focus management
-- ✅ Yeterli dokunma alanı
+## Props Reference
 
-## Performans İpuçları
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `title` | `string` | **Yes** | - | Main title |
+| `subtitle` | `string` | No | - | Subtitle text |
+| `config` | `StepHeaderConfig` | No | `{}` | Configuration options |
+| `style` | `ViewStyle` | No | - | Custom container style |
 
-1. **Memoization**: Step header'ı memo edin
-2. **Optimized Re-renders**: Sadece gerekli olduğunda güncelleyin
-3. **Minimal Props**: Gereksiz props'tan kaçının
-
-## İlgili Bileşenler
-
-- [`AtomicText`](../../atoms/AtomicText/README.md) - Metin bileşeni
-- [`BaseModal`](../BaseModal/README.md) - Modal bileşeni
-- [`FormField`](../FormField/README.md) - Form alanı
+### StepHeaderConfig
 
-## Lisans
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showStepIndicator` | `boolean` | `false` | Show step indicator |
+| `currentStep` | `number` | - | Current step (1-based) |
+| `totalSteps` | `number` | - | Total number of steps |
+| `titleAlignment` | `'left' \| 'center' \| 'right'` | `'left'` | Title alignment |
+| `titleFontSize` | `number` | `28` | Title font size |
+| `subtitleFontSize` | `number` | `16` | Subtitle font size |
+| `spacing` | `object` | - | Spacing settings |
+| `spacing.marginBottom` | `number` | `32` | Bottom margin |
+| `spacing.paddingHorizontal` | `number` | `24` | Horizontal padding |
+
+## Accessibility
+
+- ✅ Screen reader announces title and subtitle
+- ✅ Semantic heading structure (h1/h2)
+- ✅ Step progress announced
+- ✅ Focus management for keyboard navigation
+- ✅ Sufficient color contrast
+
+## Performance Tips
+
+1. **Memoization**: Memo step header to prevent re-renders
+2. **Minimal props**: Only update when step changes
+3. **Avoid inline objects**: Define config outside render
+4. **Optimize text**: Keep titles short and concise
+
+## Related Components
+
+- [`StepProgress`](../StepProgress/README.md) - Step progress bar
+- [`BaseModal`](../BaseModal/README.md) - Modal for step flows
+- [`FormField`](../FormField/README.md) - Form field component
+- [`AtomicText`](../../atoms/AtomicText/README.md) - Text component
+
+## License
 
 MIT