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

package/src/molecules/calendar/README.md

@@ -1,339 +1,375 @@
 # AtomicCalendar
 
-AtomicCalendar, React Native için tam özellikli bir takvim bileşenidir. Aylık görünümde etkinlik gösterimi, tarih seçimi ve özelleştirme desteği sunar.
+A full-featured calendar component for React Native with monthly view, event display, date selection, and timezone support.
 
-## Özellikler
+## Import & Usage
 
-- 📅 **Aylık Görünüm**: 6 haftalık 42 günlük grid
-- 🎯 **Tarih Seçimi**: Interactive tarih seçimi
-- 🔵 **Event Indicators**: Etkinlik noktaları gösterimi
-- 🌍 **Timezone Bilinci**: Timezone uyumlu
-- 🎨 **Özelleştirilebilir**: Stil ve tema desteği
-- ♿ **Erişilebilir**: Tam erişilebilirlik desteği
-- 📱 **Responsive**: Cihaz boyutuna uyum
-
-## Kurulum
-
-```tsx
-import { AtomicCalendar } from 'react-native-design-system';
+```typescript
+import { AtomicCalendar } from 'react-native-design-system/src/molecules/calendar';
 ```
 
-## Temel Kullanım
-
-```tsx
-import React, { useState } from 'react';
-import { View } from 'react-native';
-import { AtomicCalendar } from 'react-native-design-system';
-
-export const BasicExample = () => {
-  const [selectedDate, setSelectedDate] = useState(new Date());
-
-  // Calendar days'i hesaplayın (custom hook veya service kullanabilirsiniz)
-  const days = calculateCalendarDays(selectedDate);
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicCalendar
-        days={days}
-        selectedDate={selectedDate}
-        onDateSelect={setSelectedDate}
-      />
-    </View>
-  );
-};
-```
+**Location:** `src/molecules/calendar/AtomicCalendar.tsx`
 
-## Basic Calendar
+## Basic Usage
 
 ```tsx
-<AtomicCalendar
-  days={calendarDays}
-  selectedDate={selectedDate}
-  onDateSelect={(date) => setSelectedDate(date)}
-/>
-```
+const [selectedDate, setSelectedDate] = useState(new Date());
+const days = calculateCalendarDays(selectedDate);
 
-## Weekday Headers Gizle
-
-```tsx
 <AtomicCalendar
-  days={calendarDays}
+  days={days}
   selectedDate={selectedDate}
   onDateSelect={setSelectedDate}
-  showWeekdayHeaders={false}
 />
 ```
 
-## Event Indicators
+## Strategy
 
-```tsx
-<AtomicCalendar
-  days={calendarDays}
-  selectedDate={selectedDate}
-  onDateSelect={setSelectedDate}
-  maxEventIndicators={3}
-/>
-```
+**Purpose**: Provide a standardized, accessible calendar interface for date selection and event visualization.
 
-## Custom Day Style
+**When to Use**:
+- Date pickers for forms
+- Event scheduling and management
+- Appointment booking
+- Task management with due dates
+- Attendance tracking
+- Holiday/leave planning
+- Availability displays
 
-```tsx
-<AtomicCalendar
-  days={calendarDays}
-  selectedDate={selectedDate}
-  onDateSelect={setSelectedDate}
-  dayStyle={{ borderRadius: 8 }}
-/>
-```
+**When NOT to Use**:
+- For simple date selection (use DatePicker instead)
+- For date range selection only (use DateRangePicker instead)
+- For time-only selection (use TimePicker instead)
+- For recurring event configuration (use specialized scheduler UI)
 
-## Örnek Kullanımlar
+## Rules
 
-### Etkinlik Takvimi
+### Required
 
-```tsx
-export const EventCalendar = () => {
-  const [selectedDate, setSelectedDate] = useState(new Date());
-  const [events] = useState([
-    { id: 1, date: new Date(), title: 'Toplantı', color: '#6366f1' },
-    { id: 2, date: new Date(), title: 'Yemek', color: '#10b981' },
-  ]);
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicText type="headlineMedium" style={{ marginBottom: 16 }}>
-        Takvim
-      </AtomicText>
-
-      <AtomicCalendar
-        days={getCalendarDaysWithEvents(events)}
-        selectedDate={selectedDate}
-        onDateSelect={setSelectedDate}
-      />
-    </View>
-  );
-};
-```
+1. **MUST** provide `days` array (42 days, 6-week grid)
+2. **MUST** have `selectedDate` and `onDateSelect` handlers
+3. **ALWAYS** calculate days correctly with timezone handling
+4. **MUST** handle month boundaries (padding days from prev/next months)
+5. **SHOULD** show event indicators when events exist
+6. **MUST** respect isDisabled flag for unavailable dates
 
-### Randevu Takvimi
+### Day Calculation
 
-```tsx
-export const AppointmentCalendar = () => {
-  const [selectedDate, setSelectedDate] = useState(new Date());
-  const [appointments, setAppointments] = useState([]);
+1. **42-day grid**: Always return 42 days (6 weeks)
+2. **Month padding**: Include days from prev/next months to fill grid
+3. **Timezone handling**: Use consistent timezone throughout
+4. **Date validation**: Ensure all dates are valid Date objects
 
-  const handleDateSelect = (date) => {
-    setSelectedDate(date);
-    loadAppointmentsForDate(date);
-  };
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicCalendar
-        days={getCalendarDays()}
-        selectedDate={selectedDate}
-        onDateSelect={handleDateSelect}
-      />
-
-      {selectedDate && (
-        <View style={{ marginTop: 16 }}>
-          <AtomicText type="titleMedium">
-            {selectedDate.toLocaleDateString('tr-TR')}
-          </AtomicText>
-
-          {appointments.length > 0 ? (
-            appointments.map((apt) => (
-              <AppointmentCard key={apt.id} appointment={apt} />
-            ))
-          ) : (
-            <AtomicText type="bodyMedium" color="textSecondary">
-              Randevu yok
-            </AtomicText>
-          )}
-        </View>
-      )}
-    </View>
-  );
-};
-```
+### Event Indicators
 
-### Görev Takvimi
+1. **Max indicators**: Default to 3, adjust based on design
+2. **Event mapping**: Map events to correct dates
+3. **Visual distinction**: Different colors for different event types
+4. **Performance**: Limit events per day for performance
 
-```tsx
-export const TaskCalendar = () => {
-  const [selectedDate, setSelectedDate] = useState(new Date());
-
-  const getDaysWithTasks = () => {
-    const days = calculateCalendarDays(selectedDate);
-    return days.map(day => ({
-      ...day,
-      events: getTasksForDate(day.date).slice(0, 3),
-    }));
-  };
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicCalendar
-        days={getDaysWithTasks()}
-        selectedDate={selectedDate}
-        onDateSelect={setSelectedDate}
-        maxEventIndicators={5}
-      />
-    </View>
-  );
-};
-```
+## Forbidden
 
-### Doğum Günü Takvimi
+❌ **NEVER** do these:
 
 ```tsx
-export const BirthdayCalendar = () => {
-  const [selectedDate, setSelectedDate] = useState(new Date());
-  const [birthdays] = useState([
-    { id: 1, name: 'Ahmet', date: new Date(), month: 0, day: 15 },
-  ]);
-
-  const getDaysWithBirthdays = () => {
-    const days = calculateCalendarDays(selectedDate);
-    return days.map(day => ({
-      ...day,
-      events: birthdays.filter(b =>
-        b.month === day.date.getMonth() && b.day === day.date.getDate()
-      ),
-    }));
-  };
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicCalendar
-        days={getDaysWithBirthdays()}
-        selectedDate={selectedDate}
-        onDateSelect={setSelectedDate}
-      />
-    </View>
-  );
-};
-```
-
-### Check-in Takvimi
+// ❌ No days array
+<AtomicCalendar
+  selectedDate={selectedDate}
+  onDateSelect={setSelectedDate}
+/>
 
-```tsx
-export const CheckinCalendar = ({ checkins }) => {
-  const [selectedDate, setSelectedDate] = useState(new Date());
-
-  const getDaysWithCheckins = () => {
-    const days = calculateCalendarDays(selectedDate);
-    return days.map(day => ({
-      ...day,
-      hasCheckin: checkins.some(c =>
-        isSameDay(c.date, day.date)
-      ),
-    }));
-  };
-
-  return (
-    <View style={{ padding: 16 }}>
-      <AtomicCalendar
-        days={getDaysWithCheckins()}
-        selectedDate={selectedDate}
-        onDateSelect={setSelectedDate}
-      />
-    </View>
-  );
+// ❌ Wrong day count (not 42 days)
+const getDays = () => {
+  const days = [];
+  // ❌ Only returns 30 days for current month
+  for (let i = 1; i <= 30; i++) {
+    days.push({ date: new Date(year, month, i) });
+  }
+  return days;
 };
-```
 
-## Props
+// ❌ No timezone handling
+const days = calculateCalendarDays(selectedDate); // ❌ Uses local time
 
-### AtomicCalendarProps
+// ❌ Missing month padding
+const days = currentMonthDays; // ❌ No prev/next month days
 
-| Prop | Tip | Varsayılan | Açıklama |
-|------|-----|------------|----------|
-| `days` | `CalendarDay[]` | - **(Zorunlu)** | Takvim günleri (42 gün) |
-| `selectedDate` | `Date` | - **(Zorunlu)** | Seçili tarih |
-| `onDateSelect` | `(date: Date) => void` | - **(Zorunlu)** | Tarih seçim callback'i |
-| `showWeekdayHeaders` | `boolean` | `true` | Gün başlıklarını göster |
-| `maxEventIndicators` | `number` | `3` | Maksimum etkinlik sayısı |
-| `dayStyle` | `StyleProp<ViewStyle>` | - | Gün hücresi stili |
-| `showEventCount` | `boolean` | `true` | Event sayısını göster |
-| `style` | `StyleProp<ViewStyle>` | - | Container stili |
-| `testID` | `string` | - | Test ID'si |
+// ❌ Not handling disabled dates
+<AtomicCalendar
+  days={days}
+  selectedDate={new Date('2024-01-01')} // ❌ Past date
+  onDateSelect={setSelectedDate}
+/>
 
-### CalendarDay
+// ❌ Too many event indicators
+<AtomicCalendar
+  days={days}
+  selectedDate={selectedDate}
+  maxEventIndicators={20} // ❌ Too many, performance issue
+/>
 
-```typescript
-interface CalendarDay {
-  date: Date;              // Tarih
-  isCurrentMonth: boolean; // Mevcut ay mı
-  isSelected: boolean;     // Seçili mi
-  isToday: boolean;        // Bugün mü
-  events?: Event[];        // Etkinlikler
-  isDisabled?: boolean;    // Devre dışı mı
-}
+// ❌ No date validation
+const days = [
+  { date: null }, // ❌ Invalid date
+  { date: '2024-01-01' }, // ❌ String, not Date object
+];
 ```
 
 ## Best Practices
 
-### 1. Day Hesaplama
+### Day Calculation
 
+✅ **DO**:
 ```tsx
-// Takvim günlerini hesaplayın
-const calculateCalendarDays = (date: Date) => {
+// ✅ Good - 42-day grid with padding
+const calculateCalendarDays = (date: Date): CalendarDay[] => {
   const year = date.getFullYear();
   const month = date.getMonth();
   const firstDay = new Date(year, month, 1);
   const lastDay = new Date(year, month + 1, 0);
 
-  // 42 günlük grid (6 hafta)
-  const days = [];
-  // ... hesaplama logic
+  const firstDayOfWeek = firstDay.getDay(); // 0 = Sunday
+  const daysInMonth = lastDay.getDate();
+
+  const days: CalendarDay[] = [];
+
+  // Add padding days from previous month
+  for (let i = firstDayOfWeek - 1; i >= 0; i--) {
+    const prevDate = new Date(year, month, -i);
+    days.push({
+      date: prevDate,
+      isCurrentMonth: false,
+      isSelected: isSameDay(prevDate, selectedDate),
+      isToday: isSameDay(prevDate, new Date()),
+    });
+  }
+
+  // Add current month days
+  for (let i = 1; i <= daysInMonth; i++) {
+    const currentDate = new Date(year, month, i);
+    days.push({
+      date: currentDate,
+      isCurrentMonth: true,
+      isSelected: isSameDay(currentDate, selectedDate),
+      isToday: isSameDay(currentDate, new Date()),
+    });
+  }
+
+  // Add padding days from next month to reach 42
+  const remainingDays = 42 - days.length;
+  for (let i = 1; i <= remainingDays; i++) {
+    const nextDate = new Date(year, month + 1, i);
+    days.push({
+      date: nextDate,
+      isCurrentMonth: false,
+      isSelected: isSameDay(nextDate, selectedDate),
+      isToday: isSameDay(nextDate, new Date()),
+    });
+  }
+
   return days;
 };
 ```
 
-### 2. Event Mapping
+❌ **DON'T**:
+```tsx
+// ❌ Bad - only current month, no padding
+const getDays = (date: Date) => {
+  const lastDay = new Date(date.getFullYear(), date.getMonth() + 1, 0);
+  const days = [];
+  for (let i = 1; i <= lastDay.getDate(); i++) {
+    days.push({
+      date: new Date(date.getFullYear(), date.getMonth(), i),
+      isCurrentMonth: true,
+    });
+  }
+  return days; // ❌ Only 28-31 days, breaks grid layout
+};
+```
+
+### Event Mapping
 
+✅ **DO**:
 ```tsx
-// Etkinlikleri günlere map edin
-const mapEventsToDays = (days: CalendarDay[], events: Event[]) => {
+// ✅ Good - map events to days
+const getDaysWithEvents = (date: Date, events: Event[]): CalendarDay[] => {
+  const days = calculateCalendarDays(date);
   return days.map(day => ({
     ...day,
-    events: events.filter(e => isSameDay(e.date, day.date)),
+    events: events.filter(event =>
+      isSameDay(event.date, day.date)
+    ).slice(0, 3), // Limit to 3 for performance
   }));
 };
 ```
 
-### 3. Tarih Seçimi
+## AI Coding Guidelines
+
+### For AI Agents
+
+When generating AtomicCalendar components, follow these rules:
+
+1. **Always import from correct path**:
+   ```typescript
+   import { AtomicCalendar } from 'react-native-design-system/src/molecules/calendar';
+   ```
+
+2. **Always calculate 42-day grid**:
+   ```tsx
+   // ✅ Good - always 42 days
+   const calculateCalendarDays = (date: Date): CalendarDay[] => {
+     // Calculate with padding from prev/next months
+     // Must return exactly 42 days (6 weeks)
+   };
+
+   // ❌ Bad - variable day count
+   const getDays = (date: Date) => {
+     // Returns 28-31 days
+   };
+   ```
+
+3. **Always handle month boundaries**:
+   ```tsx
+   // ✅ Good - include padding days
+   const days: CalendarDay[] = [];
+
+   // Previous month padding
+   for (let i = firstDayOfWeek - 1; i >= 0; i--) {
+     days.push(createDay(new Date(year, month, -i), false));
+   }
+
+   // Current month
+   for (let i = 1; i <= daysInMonth; i++) {
+     days.push(createDay(new Date(year, month, i), true));
+   }
+
+   // Next month padding (to reach 42)
+   for (let i = 1; days.length < 42; i++) {
+     days.push(createDay(new Date(year, month + 1, i), false));
+   }
+   ```
+
+4. **Always validate date objects**:
+   ```tsx
+   // ✅ Good - validate dates
+   if (!(date instanceof Date) || isNaN(date.getTime())) {
+     throw new Error('Invalid date');
+   }
+
+   // ❌ Bad - no validation
+   const days = [{ date: someInput }]; // Could be invalid
+   ```
+
+5. **Always limit event indicators**:
+   ```tsx
+   // ✅ Good - limit events
+   const daysWithEvents = days.map(day => ({
+     ...day,
+     events: events
+       .filter(e => isSameDay(e.date, day.date))
+       .slice(0, 3), // Max 3 events
+   }));
+
+   // ❌ Bad - unlimited events
+   events.filter(e => isSameDay(e.date, day.date)) // Could be 100+
+   ```
+
+### Common Patterns
+
+#### Basic Calendar
+```tsx
+const [selectedDate, setSelectedDate] = useState(new Date());
+const days = useMemo(() => calculateCalendarDays(selectedDate), [selectedDate]);
 
+<AtomicCalendar
+  days={days}
+  selectedDate={selectedDate}
+  onDateSelect={setSelectedDate}
+/>
+```
+
+#### Calendar with Events
 ```tsx
-// Tarih seçimi
-const handleDateSelect = (date: Date) => {
-  setSelectedDate(date);
-  loadEventsForDate(date);
-};
+const [selectedDate, setSelectedDate] = useState(new Date());
+const [events, setEvents] = useState<Event[]>([]);
+
+const days = useMemo(() => {
+  const calendarDays = calculateCalendarDays(selectedDate);
+  return calendarDays.map(day => ({
+    ...day,
+    events: events
+      .filter(e => isSameDay(e.date, day.date))
+      .slice(0, 3),
+  }));
+}, [selectedDate, events]);
+
+<AtomicCalendar
+  days={days}
+  selectedDate={selectedDate}
+  onDateSelect={(date) => {
+    setSelectedDate(date);
+    loadEventsForDate(date);
+  }}
+/>
+```
+
+#### Calendar with Disabled Dates
+```tsx
+const days = useMemo(() => {
+  const calendarDays = calculateCalendarDays(selectedDate);
+  return calendarDays.map(day => ({
+    ...day,
+    isDisabled: day.date < new Date(), // Disable past dates
+  }));
+}, [selectedDate]);
 ```
 
-## Erişilebilirlik
+## Props Reference
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `days` | `CalendarDay[]` | Yes | - | Calendar days (42 days) |
+| `selectedDate` | `Date` | Yes | - | Selected date |
+| `onDateSelect` | `(date: Date) => void` | Yes | - | Date selection callback |
+| `showWeekdayHeaders` | `boolean` | No | `true` | Show weekday headers |
+| `maxEventIndicators` | `number` | No | `3` | Maximum event indicators |
+| `dayStyle` | `ViewStyle` | No | - | Day cell style |
+| `showEventCount` | `boolean` | No | `true` | Show event count |
+
+### CalendarDay Interface
+
+```typescript
+interface CalendarDay {
+  date: Date;              // Date object
+  isCurrentMonth: boolean; // Is in current month
+  isSelected: boolean;     // Is selected
+  isToday: boolean;        // Is today
+  events?: Event[];        // Events for this day
+  isDisabled?: boolean;    // Is disabled
+}
+```
 
-AtomicCalendar, tam erişilebilirlik desteği sunar:
+## Accessibility
 
-- ✅ Screen reader desteği
-- ✅ Tarih anonsu
-- ✅ Event bilgileri
-- ✅ Touch uygun boyut
+- ✅ Screen reader announces date and events
+- ✅ Touch target size maintained (min 44x44pt)
 - ✅ Keyboard navigation (web)
+- ✅ Semantic date information
+- ✅ Visual indicators for today and selected date
 
-## Performans İpuçları
+## Performance Tips
 
-1. **Memoization**: `days` array'ini memo edin
-2. **Lazy Loading**: Event'leri lazy load edin
-3. **Virtualization**: Uzun listelerde virtualization kullanın
+1. **Memoization**: Always memo `days` array with useMemo
+2. **Limit events**: Max 3-5 event indicators per day
+3. **Lazy load**: Load events only when needed
+4. **Debounce selection**: Debounce rapid date changes
 
-## İlgili Bileşenler
+## Related Components
 
-- [`AtomicDatePicker`](../../atoms/AtomicDatePicker/README.md) - Tarih seçici
-- [`FormField`](../FormField/README.md) - Form alanı
-- [`AtomicButton`](../../atoms/button/README.md) - Buton bileşeni
+- [`BaseModal`](../BaseModal/README.md) - Modal component
+- [`FormField`](../FormField/README.md) - Form field component
+- [`Button`](../../atoms/button/README.md) - Button component
 
-## Lisans
+## License
 
 MIT