@umituz/react-native-design-system 2.6.93 → 2.6.95

package/src/atoms/button/README.md

@@ -1,363 +1,252 @@
-# AtomicButton
+# Button
 
-AtomicButton, React Native için güçlü ve özelleştirilebilir bir buton bileşenidir. Material Design 3 prensiplerine uygun olarak tasarlanmış ve tamamen özelleştirilebilir.
+Clickable button component with multiple variants and sizes for React Native applications.
 
-## Özellikler
+## Import & Usage
 
-- ✨ **6 Variant**: Primary, Secondary, Tertiary, Surface, Outline, Ghost
-- 📏 **3 Size**: Small, Medium, Large
-- 🎨 **Tam Özelleştirilebilir**: Stil ve metin özelleştirmesi
-- 🔄 **Loading State**: Yükleme durumu
-- 🎭 **İkon Desteği**: Sol veya sağ ikon
-- 📐 **Full Width**: Tam genişlik desteği
-- ♿ **Erişilebilirlik**: Tam erişilebilirlik desteği
+```typescript
+import { Button } from 'react-native-design-system/src/atoms/button';
+```
+
+**Location:** `src/atoms/button/Button.tsx`
 
-## Kurulum
+## Basic Usage
 
 ```tsx
-import { AtomicButton } from 'react-native-design-system';
+<Button title="Click me" onPress={handlePress} />
 ```
 
-## Temel Kullanım
+## Strategy
 
-```tsx
-import React from 'react';
-import { View } from 'react-native';
-import { AtomicButton } from 'react-native-design-system';
-
-export const BasicExample = () => {
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicButton
-        title="Buton"
-        onPress={() => console.log('Tıklandı!')}
-      />
-    </View>
-  );
-};
-```
+**Purpose**: Provide consistent, accessible, and performant button interactions throughout the application.
 
-## Variant'lar
+**When to Use**:
+- Primary actions (submit, confirm, save)
+- Secondary actions (cancel, go back)
+- Destructive actions (delete, remove)
+- Navigation actions (open link, go to screen)
 
-```tsx
-<View style={{ gap: 12 }}>
-  {/* Primary */}
-  <AtomicButton
-    variant="primary"
-    title="Primary"
-    onPress={() => {}}
-  />
-
-  {/* Secondary */}
-  <AtomicButton
-    variant="secondary"
-    title="Secondary"
-    onPress={() => {}}
-  />
-
-  {/* Tertiary */}
-  <AtomicButton
-    variant="tertiary"
-    title="Tertiary"
-    onPress={() => {}}
-  />
-
-  {/* Surface */}
-  <AtomicButton
-    variant="surface"
-    title="Surface"
-    onPress={() => {}}
-  />
-
-  {/* Outline */}
-  <AtomicButton
-    variant="outline"
-    title="Outline"
-    onPress={() => {}}
-  />
-
-  {/* Ghost */}
-  <AtomicButton
-    variant="ghost"
-    title="Ghost"
-    onPress={() => {}}
-  />
-</View>
-```
+**When NOT to Use**:
+- For navigation - use Navigation components instead
+- For complex interactions - use Pressable or TouchableOpacity
+- For icon-only buttons - use IconButton instead
 
-## Boyutlar
+## Rules
 
-```tsx
-<View style={{ gap: 12 }}>
-  {/* Small */}
-  <AtomicButton
-    size="sm"
-    title="Small"
-    onPress={() => {}}
-  />
-
-  {/* Medium (Varsayılan) */}
-  <AtomicButton
-    size="md"
-    title="Medium"
-    onPress={() => {}}
-  />
-
-  {/* Large */}
-  <AtomicButton
-    size="lg"
-    title="Large"
-    onPress={() => {}}
-  />
-</View>
-```
+### Required
 
-## İkonlu Butonlar
+1. **ALWAYS** provide a `title` prop (except for loading state)
+2. **MUST** have an `onPress` handler (unless disabled)
+3. **NEVER** nest buttons inside buttons
+4. **ALWAYS** provide accessible label for icon-only buttons
+5. **MUST** have adequate touch target size (min 44x44pt)
 
-```tsx
-<View style={{ gap: 12 }}>
-  {/* Sol İkon */}
-  <AtomicButton
-    title="Devam Et"
-    icon="arrow-forward-outline"
-    iconPosition="left"
-    onPress={() => {}}
-  />
-
-  {/* Sağ İkon */}
-  <AtomicButton
-    title="Geri"
-    icon="arrow-back-outline"
-    iconPosition="right"
-    onPress={() => {}}
-  />
-
-  {/* Sadece İkon */}
-  <AtomicButton
-    icon="add-outline"
-    onPress={() => {}}
-  />
-</View>
-```
+### Disabled State
 
-## Loading State
+1. **MUST** visually indicate disabled state
+2. **MUST NOT** respond to touch when disabled
+3. **SHOULD** provide reason for disabled state (tooltip or hint)
 
-```tsx
-<AtomicButton
-  title="Yükleniyor"
-  loading
-  onPress={() => {}}
-/>
-```
+### Variants
 
-## Disabled State
+1. **Primary**: Single primary action per screen/section
+2. **Secondary**: Multiple secondary actions allowed
+3. **Destructive**: Reserved for destructive actions only
+4. **Ghost**: For tertiary actions or cancel buttons
 
-```tsx
-<AtomicButton
-  title="Devre Dışı"
-  disabled
-  onPress={() => {}}
-/>
-```
+## Forbidden
 
-## Full Width
+❌ **NEVER** do these:
 
 ```tsx
-<AtomicButton
-  title="Tam Genişlik"
-  fullWidth
-  onPress={() => {}}
-/>
-```
+// ❌ Empty buttons
+<Button />
 
-## Örnek Kullanımlar
+// ❌ Nested buttons
+<Button onPress={action1}>
+  <Button onPress={action2} />
+</Button>
 
-### Form Gönderme
+// ❌ Buttons without onPress
+<Button title="Click me" />
 
-```tsx
-<AtomicButton
-  variant="primary"
-  size="lg"
-  title="Gönder"
-  loading={isSubmitting}
-  onPress={handleSubmit}
-/>
-```
+// ❌ Inline buttons (use Link instead)
+<View style={{ flexDirection: 'row' }}>
+  <Text>Click </Text>
+  <Button title="here" />
+</View>
 
-### Silme İşlemi
+// ❌ Too many primary buttons
+<View>
+  <Button variant="primary" title="Save" />
+  <Button variant="primary" title="Cancel" /> {/* ❌ Use ghost */}
+</View>
 
-```tsx
-<AtomicButton
-  variant="outline"
-  title="Sil"
-  icon="trash-outline"
-  onPress={handleDelete}
-/>
+// ❌ Hardcoded text (use i18n)
+<Button title="Submit" /> {/* ❌ Use t('buttons.submit') */}
 ```
 
-### İptal
+## Best Practices
 
-```tsx
-<AtomicButton
-  variant="ghost"
-  title="İptal"
-  onPress={handleCancel}
-/>
-```
+### Button Placement
 
-### İkon Butonları
+✅ **DO**:
+- Place primary action at bottom-right or top-right
+- Group related actions together
+- Use consistent button order (Cancel, OK) or (OK, Cancel)
 
-```tsx
-<View style={{ flexDirection: 'row', gap: 8 }}>
-  <AtomicButton
-    variant="surface"
-    icon="add-outline"
-    onPress={() => {}}
-  />
-
-  <AtomicButton
-    variant="surface"
-    icon="create-outline"
-    onPress={() => {}}
-  />
-
-  <AtomicButton
-    variant="surface"
-    icon="trash-outline"
-    onPress={() => {}}
-  />
-</View>
-```
+❌ **DON'T**:
+- Place primary action in middle of other actions
+- Mix button order inconsistently
+- Use too many buttons on one screen
 
-## Props
-
-### AtomicButtonProps
-
-| Prop | Tip | Varsayılan | Açıklama |
-|------|-----|------------|----------|
-| `title` | `string` | - | Buton metni |
-| `children` | `ReactNode` | - | Alternatif içerik |
-| `onPress` | `() => void` | - **(Zorunlu)** | Tıklama olayı |
-| `variant` | `ButtonVariant` | `'primary'` | Buton görünüm stili |
-| `size` | `ButtonSize` | `'md'` | Buton boyutu |
-| `disabled` | `boolean` | `false` | Devre dışı |
-| `loading` | `boolean` | `false` | Yükleme durumu |
-| `icon` | `string` | - | İkon ismi (Ionicons) |
-| `iconPosition` | `'left' \| 'right'` | `'left'` | İkon konumu |
-| `fullWidth` | `boolean` | `false` | Tam genişlik |
-| `style` | `StyleProp<ViewStyle>` | - | Container stil |
-| `textStyle` | `StyleProp<TextStyle>` | - | Metin stil |
-| `activeOpacity` | `number` | `0.8` | Opaklık |
-| `testID` | `string` | - | Test ID'si |
-
-### ButtonVariant
+### Button Wording
 
-```typescript
-type ButtonVariant =
-  | 'primary'    // Ana buton
-  | 'secondary'  // İkincil buton
-  | 'tertiary'   // Üçüncül buton
-  | 'surface'    // Yüzey butonu
-  | 'outline'    // Çerçeveli buton
-  | 'ghost';     // Hayalet buton
-```
+✅ **DO**:
+- Use action verbs (Save, Delete, Cancel)
+- Be specific (Save Draft vs Save)
+- Use sentence case
+- Keep short (1-3 words)
 
-### ButtonSize
+❌ **DON'T**:
+- Use ambiguous text (OK, Sure, Submit)
+- Use long text (I agree to the terms and conditions)
+- Use all caps (CLICK HERE)
 
-```typescript
-type ButtonSize = 'sm' | 'md' | 'lg';
-```
+### Loading State
 
-## Stil Özelleştirme
+✅ **DO**:
+```tsx
+<Button loading={isLoading} onPress={handleSubmit}>
+  {isLoading ? 'Saving...' : 'Save'}
+</Button>
+```
 
+❌ **DON'T**:
 ```tsx
-<AtomicButton
-  title="Özel Buton"
-  onPress={() => {}}
-  style={{
-    backgroundColor: '#6366f1',
-    borderRadius: 8,
-    shadowColor: '#6366f1',
-    shadowOffset: { width: 0, height: 4 },
-    shadowOpacity: 0.3,
-    shadowRadius: 8,
-    elevation: 8,
-  }}
-  textStyle={{
-    color: '#ffffff',
-    fontSize: 16,
-    fontWeight: '700',
-  }}
-/>
+// Don't disable entire form during load
+<Button disabled={isLoading} />
 ```
 
-## Best Practices
+## AI Coding Guidelines
 
-### 1. Buton Hiyerarşisi
+### For AI Agents
 
-```tsx
-// Ana eylem
-<AtomicButton variant="primary" title="Kaydet" onPress={save} />
+When generating Button components, follow these rules:
 
-// İkincil eylem
-<AtomicButton variant="secondary" title="İptal" onPress={cancel} />
+1. **Always import from correct path**:
+   ```typescript
+   import { Button } from 'react-native-design-system/src/atoms/button';
+   ```
 
-// Tehlikeli eylem
-<AtomicButton variant="outline" title="Sil" onPress={delete} />
-```
+2. **Always provide required props**:
+   ```tsx
+   <Button
+     title="明确且简洁的标题"
+     onPress={具体的处理函数}
+     variant="根据上下文选择合适的变体"
+   />
+   ```
+
+3. **Always handle loading state**:
+   ```tsx
+   const [loading, setLoading] = useState(false);
 
-### 2. İkon Kullanımı
+   <Button
+     loading={loading}
+     onPress={async () => {
+       setLoading(true);
+       await handleAction();
+       setLoading(false);
+     }}
+   />
+   ```
 
+4. **Always use i18n for text**:
+   ```tsx
+   <Button title={t('common.save')} onPress={handleSave} />
+   ```
+
+5. **Never disable without reason**:
+   ```tsx
+   // ❌ Bad
+   <Button disabled={true} />
+
+   // ✅ Good
+   <Button disabled={!form.isValid} title={form.error || 'Complete form'} />
+   ```
+
+### Common Patterns
+
+#### Form Submit Button
 ```tsx
-// İlerle - sağ ikon
-<AtomicButton
-  title="İlerle"
-  icon="arrow-forward"
-  iconPosition="right"
-  onPress={next}
+<Button
+  variant="primary"
+  title={t('form.submit')}
+  onPress={handleSubmit}
+  disabled={!isFormValid}
+  loading={isSubmitting}
 />
+```
 
-// Geri - sol ikon
-<AtomicButton
-  title="Geri"
-  icon="arrow-back"
-  iconPosition="left"
-  onPress={back}
+#### Destructive Action
+```tsx
+<Button
+  variant="destructive"
+  title={t('common.delete')}
+  onPress={handleDelete}
+  confirmRequired={true}
 />
 ```
 
-### 3. Loading State
-
+#### Cancel Action
 ```tsx
-<AtomicButton
-  title="Gönder"
-  loading={isLoading}
-  onPress={handleSubmit}
-  disabled={isLoading}
+<Button
+  variant="ghost"
+  title={t('common.cancel')}
+  onPress={handleCancel}
 />
 ```
 
-## Erişilebilirlik
+## Props Reference
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `title` | `string` | Yes* | - | Button text (*not required for loading) |
+| `onPress` | `() => void` | Yes | - | Press handler |
+| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'destructive'` | No | `'primary'` | Visual style |
+| `size` | `'small' \| 'medium' \| 'large'` | No | `'medium'` | Button size |
+| `disabled` | `boolean` | No | `false` | Disable button |
+| `loading` | `boolean` | No | `false` | Show loading indicator |
+| `fullWidth` | `boolean` | No | `false` | Expand to full width |
+| `icon` | `string` | No | - | Icon name (Ionicons) |
+
+## Accessibility
+
+- ✅ Screen reader announces button title
+- ✅ Minimum touch target: 44x44pt
+- ✅ Focus visible on keyboard navigation
+- ✅ Disabled state announced to screen readers
+- ✅ Loading state announced to screen readers
 
-AtomicButton, tam erişilebilirlik desteği sunar:
+## Performance
 
-- ✅ Touch uygun boyut (minimum 44x44)
-- ✅ Screen reader desteği
-- ✅ Disabled state anonsu
-- ✅ Test ID desteği
+1. **Memo handlers**: Use `useCallback` for onPress handlers
+2. **Avoid inline functions**: Don't create functions in render
+3. **Conditional rendering**: Don't render disabled buttons if action unavailable
 
-## Performans İpuçları
+## Related Components
 
-1. **React.memo**: AtomicButton zaten `React.memo` ile sarılmış
-2. **Inline Styles**: Inline stil kullanmaktan kaçının, bunun yerine theme kullanın
-3. **Re-renders**: Prop'ları stabilize edin (useCallback, useMemo)
+- [`IconButton`](./icon-button/README.md) - Icon-only buttons
+- [`Link`](./link/README.md) - Navigation links
+- [`Pressable`](../pressable/README.md) - Custom pressable components
 
-## İlgili Bileşenler
+## Version History
 
-- [`AtomicIcon`](../AtomicIcon/README.md) - İkon bileşeni
-- [`AtomicSpinner`](../AtomicSpinner/README.md) - Yükleme göstergesi
-- [`AtomicText`](../AtomicText/README.md) - Metin bileşeni
+- **2.6.0**: Added loading prop
+- **2.5.0**: Added fullWidth support
+- **2.0.0**: Initial release with 4 variants
 
-## Lisans
+## License
 
 MIT