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

package/src/atoms/AtomicDatePicker.README.md

@@ -1,399 +1,194 @@
 # AtomicDatePicker
 
-AtomicDatePicker, platforma özel native tarih/saat seçici bileşenidir. iOS ve Android'de tutarlı bir deneyim sunar.
+A platform-native date/time picker component for React Native.
 
-## Özellikler
+## Import & Usage
 
-- 📅 **Tarih Seçimi**: Native tarih picker
-- ⏰ **Saat Seçimi**: Native saat picker
-- 🌍 **Locale Desteği**: Otomatik dil entegrasyonu
-- 🎨 **Tema Bilinci**: Tema entegrasyonu
-- 📱 **Platform Spesifik**: iOS wheel, Android dialog
-- ⚙️ **Kısıtlamalar**: Min/Maks tarih
-- ♿ **Erişilebilir**: Tam erişilebilirlik desteği
-
-## Kurulum
-
-```tsx
-import { AtomicDatePicker } from 'react-native-design-system';
+```typescript
+import { AtomicDatePicker } from 'react-native-design-system/src/atoms/AtomicDatePicker';
 ```
 
-## Temel Kullanım
-
-```tsx
-import React, { useState } from 'react';
-import { View } from 'react-native';
-import { AtomicDatePicker } from 'react-native-design-system';
-
-export const BasicExample = () => {
-  const [selectedDate, setSelectedDate] = useState<Date | null>(null);
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicDatePicker
-        value={selectedDate}
-        onChange={setSelectedDate}
-        label="Doğum Tarihi"
-        placeholder="Tarih seçin"
-      />
-    </View>
-  );
-};
-```
+**Location:** `src/atoms/AtomicDatePicker.tsx`
 
-## Date Picker
+## Basic Usage
 
 ```tsx
-const [date, setDate] = useState<Date | null>(null);
-
 <AtomicDatePicker
   value={date}
   onChange={setDate}
-  mode="date"
-  label="Tarih"
-  placeholder="Tarih seçin"
+  label="Birthday"
+  placeholder="Select date"
 />
 ```
 
-## Time Picker
+## Strategy
 
-```tsx
-const [time, setTime] = useState<Date | null>(null);
+**Purpose**: Provide native date/time selection with platform-appropriate UI.
 
-<AtomicDatePicker
-  value={time}
-  onChange={setTime}
-  mode="time"
-  label="Saat"
-  placeholder="Saat seçin"
-/>
-```
+**When to Use**:
+- Date selection (birthdays, appointments, events)
+- Time selection (reminders, scheduling)
+- Date ranges (start/end dates)
+- Any date/time input
 
-## DateTime Picker (Sadece iOS)
+**When NOT to Use**:
+- For custom calendar UI (build custom component)
+- When using non-standard calendars
 
-```tsx
-const [dateTime, setDateTime] = useState<Date | null>(null);
+## Rules
 
-<AtomicDatePicker
-  value={dateTime}
-  onChange={setDateTime}
-  mode="datetime"
-  label="Tarih ve Saat"
-  placeholder="Tarih ve saat seçin"
-/>
-```
+### Required
 
-## Min/Max Date
+1. **MUST** provide `value` and `onChange`
+2. **SHOULD** provide `label` for accessibility
+3. **MUST** show error messages clearly
+4. **ALWAYS** set appropriate `mode` (date, time, datetime)
+5. **SHOULD** use `minimumDate`/`maximumDate` for constraints
+6. **MUST** validate dates appropriately
 
-```tsx
-<AtomicDatePicker
-  value={birthDate}
-  onChange={setBirthDate}
-  label="Doğum Tarihi"
-  minimumDate={new Date(1900, 0, 1)}
-  maximumDate={new Date()}
-/>
-```
+### Date Validation
 
-## Error State
+1. **Future dates**: Birthdays, events
+2. **Past dates**: Historical dates
+3. **Ranges**: Set min/max appropriately
+4. **Business rules**: Enforce date constraints
 
-```tsx
-<AtomicDatePicker
-  value={date}
-  onChange={setDate}
-  label="Tarih"
-  error="Lütfen geçerli bir tarih seçin"
-/>
-```
+## Forbidden
 
-## Disabled
+❌ **NEVER** do these:
 
 ```tsx
+// ❌ No value or onChange
 <AtomicDatePicker
-  value={date}
-  onChange={setDate}
-  label="Tarih"
-  disabled
+  label="Birthday"
+  placeholder="Select date"
+  // ❌ Missing value and onChange
 />
-```
 
-## Örnek Kullanımlar
-
-### Doğum Tarihi
-
-```tsx
-export const BirthDateForm = () => {
-  const [birthDate, setBirthDate] = useState<Date | null>(null);
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicDatePicker
-        value={birthDate}
-        onChange={setBirthDate}
-        label="Doğum Tarihi"
-        placeholder="Doğum tarihinizi seçin"
-        minimumDate={new Date(1900, 0, 1)}
-        maximumDate={new Date()}
-        mode="date"
-      />
-
-      {birthDate && (
-        <AtomicText type="bodyMedium" marginTop="sm">
-          Seçilen Tarih: {birthDate.toLocaleDateString('tr-TR')}
-        </AtomicText>
-      )}
-    </View>
-  );
-};
-```
+// ❌ Wrong mode
+<AtomicDatePicker
+  mode="datetime" {/* ❌ Android doesn't support */}
+/>
 
-### Randevu Tarihi
+// ❌ No date constraints
+<AtomicDatePicker
+  label="Birthday"
+  // ❌ Should have maximumDate
+/>
 
-```tsx
-export const AppointmentForm = () => {
-  const [appointmentDate, setAppointmentDate] = useState<Date | null>(null);
-  const [error, setError] = useState('');
-
-  const handleDateChange = (date: Date) => {
-    const today = new Date();
-    today.setHours(0, 0, 0, 0);
-
-    if (date < today) {
-      setError('Geçmiş tarih seçemezsiniz');
-      return;
-    }
-
-    setError('');
-    setAppointmentDate(date);
-  };
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicDatePicker
-        value={appointmentDate}
-        onChange={handleDateChange}
-        label="Randevu Tarihi"
-        placeholder="Randevu tarihi seçin"
-        minimumDate={new Date()}
-        error={error}
-        mode="date"
-      />
-    </View>
-  );
-};
+// ❌ Generic error
+<AtomicDatePicker
+  error="Invalid date" {/* ❌ Not actionable */}
+/>
 ```
 
-### Etkinlik Tarihi ve Saati
-
-```tsx
-export const EventForm = () => {
-  const [eventDateTime, setEventDateTime] = useState<Date | null>(null);
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicDatePicker
-        value={eventDateTime}
-        onChange={setEventDateTime}
-        label="Etkinlik Tarihi ve Saati"
-        placeholder="Tarih ve saat seçin"
-        minimumDate={new Date()}
-        mode="datetime"
-      />
-
-      {eventDateTime && (
-        <AtomicText type="bodyMedium" marginTop="sm">
-          {eventDateTime.toLocaleString('tr-TR')}
-        </AtomicText>
-      )}
-    </View>
-  );
-};
-```
+## Best Practices
 
-### Hatırlatıcı Saati
+### Date Constraints
 
+✅ **DO**:
 ```tsx
-export const ReminderForm = () => {
-  const [reminderTime, setReminderTime] = useState<Date | null>(null);
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicDatePicker
-        value={reminderTime}
-        onChange={setReminderTime}
-        label="Hatırlatıcı Saati"
-        placeholder="Saat seçin"
-        mode="time"
-      />
-
-      {reminderTime && (
-        <AtomicText type="bodyMedium" marginTop="sm">
-          {reminderTime.toLocaleTimeString('tr-TR', {
-            hour: '2-digit',
-            minute: '2-digit',
-          })}
-        </AtomicText>
-      )}
-    </View>
-  );
-};
+<AtomicDatePicker
+  label="Birthday"
+  value={birthDate}
+  onChange={setBirthDate}
+  minimumDate={new Date(1900, 0, 1)}
+  maximumDate={new Date()}
+/>
 ```
 
-### Geçerlilik Tarihi
-
+❌ **DON'T**:
 ```tsx
-export const ExpiryForm = () => {
-  const [expiryDate, setExpiryDate] = useState<Date | null>(null);
-
-  const today = new Date();
-  const nextYear = new Date();
-  nextYear.setFullYear(today.getFullYear() + 1);
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicDatePicker
-        value={expiryDate}
-        onChange={setExpiryDate}
-        label="Geçerlilik Tarihi"
-        placeholder="Son kullanma tarihi"
-        minimumDate={today}
-        maximumDate={nextYear}
-        mode="date"
-      />
-    </View>
-  );
-};
+// ❌ No constraints
+<AtomicDatePicker
+  label="Birthday"
+  value={birthDate}
+  onChange={setBirthDate}
+  // User can select any date
+/>
 ```
 
-### Tarih Aralığı
+## AI Coding Guidelines
 
-```tsx
-export const DateRangeForm = () => {
-  const [startDate, setStartDate] = useState<Date | null>(null);
-  const [endDate, setEndDate] = useState<Date | null>(null);
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicDatePicker
-        value={startDate}
-        onChange={(date) => {
-          setStartDate(date);
-          if (endDate && date > endDate) {
-            setEndDate(null);
-          }
-        }}
-        label="Başlangıç Tarihi"
-        placeholder="Başlangıç tarihi"
-        mode="date"
-      />
-
-      <AtomicDatePicker
-        value={endDate}
-        onChange={setEndDate}
-        label="Bitiş Tarihi"
-        placeholder="Bitiş tarihi"
-        minimumDate={startDate || undefined}
-        mode="date"
-        style={{ marginTop: 16 }}
-      />
-    </View>
-  );
-};
-```
+### For AI Agents
 
-## Props
-
-### AtomicDatePickerProps
-
-| Prop | Tip | Varsayılan | Açıklama |
-|------|-----|------------|----------|
-| `value` | `Date \| null` | - **(Zorunlu)** | Seçili tarih |
-| `onChange` | `(date: Date) => void` | - **(Zorunlu)** | Değişiklik olayı |
-| `label` | `string` | - | Etiket metni |
-| `error` | `string` | - | Hata mesajı |
-| `disabled` | `boolean` | `false` | Devre dışı |
-| `minimumDate` | `Date` | - | Minimum tarih |
-| `maximumDate` | `Date` | - | Maksimum tarih |
-| `mode` | `'date' \| 'time' \| 'datetime'` | `'date'` | Picker modu |
-| `placeholder` | `string` | `'Select date'` | Placeholder metni |
-| `style` | `StyleProp<ViewStyle>` | - | Özel stil |
-| `testID` | `string` | - | Test ID'si |
-
-## Platform Davranışı
-
-### iOS
-- ✨ Bottom sheet modal açılır
-- 🎡 Wheel picker gösterir
-- ✅ "Done" butonu ile onaylar
-- 👆 Swipe down ile kapatılır
-
-### Android
-- 📱 Dialog açılır
-- 📅 Takvim view gösterir
-- ✅ Seçimde otomatik kapanır
+1. **Always provide value and onChange**:
+   ```tsx
+   // ✅ Good
+   const [date, setDate] = useState<Date | null>(null);
+   <AtomicDatePicker value={date} onChange={setDate} label="Date" />
 
-## Best Practices
+   // ❌ Bad
+   <AtomicDatePicker label="Date" />
+   ```
 
-### 1. Mode Seçimi
+2. **Always set date constraints**:
+   ```tsx
+   // ✅ Good
+   <AtomicDatePicker
+     label="Birthday"
+     maximumDate={new Date()}
+   />
 
-```tsx
-// Sadece tarih
-<AtomicDatePicker mode="date" />
+   // ❌ Bad
+   <AtomicDatePicker label="Birthday" />
+   ```
 
-// Sadece saat
-<AtomicDatePicker mode="time" />
+3. **Always use appropriate mode**:
+   ```tsx
+   // ✅ Good - correct mode
+   <AtomicDatePicker mode="date" />
+   <AtomicDatePicker mode="time" />
 
-// Tarih ve saat (sadece iOS)
-<AtomicDatePicker mode="datetime" />
-```
+   // ❌ Bad - datetime on Android
+   <AtomicDatePicker mode="datetime" />
+   ```
 
-### 2. Tarih Kısıtlamaları
+### Common Patterns
 
+#### Date Picker
 ```tsx
-// Geçmiş tarih için
 <AtomicDatePicker
-  maximumDate={new Date()}
-/>
-
-// Gelecek tarih için
-<AtomicDatePicker
-  minimumDate={new Date()}
+  label="Date"
+  value={date}
+  onChange={setDate}
+  mode="date"
 />
+```
 
-// Belirli aralık
+#### Time Picker
+```tsx
 <AtomicDatePicker
-  minimumDate={new Date(2024, 0, 1)}
-  maximumDate={new Date(2024, 11, 31)}
+  label="Time"
+  value={time}
+  onChange={setTime}
+  mode="time"
 />
 ```
 
-### 3. Error Handling
-
-```tsx
-const validateDate = (date: Date) => {
-  const today = new Date();
-  if (date < today) {
-    return 'Geçmiş tarih seçemezsiniz';
-  }
-  return '';
-};
-```
+## Props Reference
 
-## Erişilebilirlik
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `value` | `Date \| null` | Yes | - | Selected date |
+| `onChange` | `(date: Date) => void` | Yes | - | Change callback |
+| `label` | `string` | No | - | Field label |
+| `error` | `string` | No | - | Error message |
+| `mode` | `'date' \| 'time' \| 'datetime'` | No | `'date'` | Picker mode |
+| `minimumDate` | `Date` | No | - | Minimum date |
+| `maximumDate` | `Date` | No | - | Maximum date |
 
-AtomicDatePicker, tam erişilebilirlik desteği sunar:
+## Accessibility
 
-- ✅ Screen reader desteği
-- ✅ Native picker erişilebilirliği
-- ✅ Error state anonsu
-- ✅ Test ID desteği
+- ✅ Screen reader support
+- ✅ Native picker accessibility
+- ✅ Error state announcement
 
-## İlgili Bileşenler
+## Related Components
 
-- [`AtomicInput`](./input/README.md) - Input bileşeni
-- [`FormField`](../../molecules/FormField/README.md) - Form alanı
-- [`AtomicPicker`](./picker/README.md) - Seçim bileşeni
+- [`AtomicInput`](./AtomicInput.README.md) - Text input
+- [`FormField`](../molecules/FormField) - Form wrapper
 
-## Lisans
+## License
 
 MIT