Skip to main content

Calendar Component Documentation

Dokumentasi lengkap untuk reusable Calendar Component yang dibangun dengan React Big Calendar, React Query, dan TypeScript.

📚 Daftar Dokumentasi​

Dokumentasi ini terdiri dari 4 file utama:

1. 📖 Calendar Component - Full Documentation​

File: calendar-component.md

Dokumentasi lengkap tentang Calendar Component, mencakup:

  • Overview & fitur-fitur
  • API Reference lengkap
  • Props & types detail
  • 7+ contoh penggunaan
  • Data normalization
  • React Query integration
  • Localization
  • Common pitfalls
  • Testing guide
  • Migration guide

Kapan membaca: Saat pertama kali ingin memahami component secara mendalam atau butuh referensi API lengkap.

2. 🚀 Installation Guide​

File: calendar-installation.md

Panduan step-by-step untuk menginstall dan setup Calendar ke project baru:

  • Prerequisites & dependencies
  • File structure & copy files
  • Setup React Query
  • Import styles
  • Adjust import paths
  • Setup Day.js
  • Basic implementation
  • CRUD operations
  • Configuration
  • Customize UI
  • Testing setup
  • Troubleshooting

Kapan membaca: Saat ingin mengimplementasikan Calendar Component ke project baru.

3. 💡 Best Practices & Tips​

File: calendar-best-practices.md

Best practices, patterns, dan tips advanced:

  • Architecture patterns (hooks, context)
  • Performance optimization
  • Styling best practices (CSS-in-JS, Tailwind)
  • Security best practices
  • Mobile optimization
  • Testing patterns
  • Error handling
  • Analytics & monitoring
  • Advanced tips (multi-tenant, DnD)
  • Production checklist

Kapan membaca: Setelah berhasil implementasi basic, ingin optimize dan improve kualitas code.

4. ⚡ Quick Reference​

File: calendar-quick-reference.md

Cheatsheet untuk penggunaan cepat:

  • Installation command
  • Basic usage
  • Common props table
  • Event object structure
  • 15+ common patterns
  • Event handlers
  • Styling snippets
  • React Query config
  • Troubleshooting quick fixes
  • Mobile setup
  • Performance tips
  • TypeScript types

Kapan membaca: Saat development, butuh referensi cepat tanpa perlu baca dokumentasi lengkap.

🎯 Reading Path​

Path 1: Implementasi Baru (First Time)​

  1. ✅ Baca Installation Guide (Step 1-11)
  2. ✅ Setup basic calendar
  3. ✅ Baca Quick Reference untuk patterns
  4. ✅ Lihat Full Documentation untuk detail API
  5. ✅ Baca Best Practices untuk optimization

Estimasi waktu: 2-3 jam

Path 2: Quick Start (Sudah Familiar)​

  1. ✅ Lihat Quick Reference
  2. ✅ Copy pattern yang sesuai
  3. ✅ Adjust sesuai kebutuhan

Estimasi waktu: 15-30 menit

Path 3: Deep Dive (Advanced)​

  1. ✅ Baca Full Documentation cover-to-cover
  2. ✅ Baca Best Practices untuk patterns
  3. ✅ Review source code di components/Calendar/
  4. ✅ Experiment dengan custom implementations

Estimasi waktu: 4-6 jam

📁 Struktur Component​

components/Calendar/
├── index.tsx                    # Legacy wrapper
├── GenericCalendar.tsx          # Main component (recommended) ⭐
├── CustomEvent.tsx              # Custom event renderer
├── CustomToolbar.tsx            # Custom toolbar component
├── Calendar.module.css          # Styling
├── types.ts                     # TypeScript types
└── utils/
    └── helper.ts                # Helper functions

🚀 Quick Start​

Minimal Setup​

# Install dependencies
npm install react-big-calendar date-fns dayjs @tanstack/react-query
// Import component
import { GenericOptimizedCalendar } from '@/components/Calendar/GenericCalendar';

// Use in your app
<div style={{ height: '600px' }}>
  <GenericOptimizedCalendar
    onFetchEvents={async (start, end) => {
      const res = await fetch(`/api/events?start=${start}&end=${end}`);
      return res.json();
    }}
  />
</div>

That's it! ✨

🎨 Features Highlight​

✅ Core Features​

  • Full TypeScript support
  • React Query integration (auto-caching)
  • Multiple views (month, week, day, agenda)
  • Custom event colors
  • Localization (ID default, customizable)
  • Responsive & mobile-friendly

✅ Advanced Features​

  • Time window restriction (jam kerja)
  • Working days filter
  • Overlap prevention
  • Date range restrictions (past/future)
  • Custom event renderer
  • Custom toolbar
  • Manual refresh API
  • Disabled states

✅ Developer Experience​

  • Fully typed with TypeScript
  • Comprehensive documentation
  • Multiple usage examples
  • Best practices guide
  • Quick reference cheatsheet
  • Testing examples

📦 Dependencies​

Required​

{
  "react": "^18.2.0",
  "react-big-calendar": "^1.8.5",
  "date-fns": "^3.0.0",
  "dayjs": "^1.11.10",
  "@tanstack/react-query": "^5.0.0"
}

Optional (for UI)​

{
  "@mantine/core": "^7.5.0",
  "@mantine/hooks": "^7.5.0",
  "@tabler/icons-react": "^2.46.0"
}

🎯 Common Use Cases​

1. Simple Event Calendar​

<GenericOptimizedCalendar
  onFetchEvents={fetchEvents}
/>

2. Working Hours Calendar​

<GenericOptimizedCalendar
  onFetchEvents={fetchEvents}
  timeWindow={{ start: '08:00', end: '17:00' }}
  workingDays={[1, 2, 3, 4, 5]}
/>

3. No Overlap Calendar​

<GenericOptimizedCalendar
  onFetchEvents={fetchEvents}
  preventOverlap={true}
/>

4. Custom Colors Calendar​

<GenericOptimizedCalendar
  onFetchEvents={fetchEvents}
  getEventColor={(event) => event.color || '#3174ad'}
/>

Lihat Quick Reference untuk lebih banyak contoh!

🧪 Testing​

import { render, waitFor } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { GenericOptimizedCalendar } from './GenericCalendar';

test('renders calendar with events', async () => {
  const mockFetch = jest.fn().mockResolvedValue([
    { id: '1', title: 'Test', start: new Date(), end: new Date() }
  ]);

  render(
    <QueryClientProvider client={new QueryClient()}>
      <div style={{ height: '600px' }}>
        <GenericOptimizedCalendar onFetchEvents={mockFetch} />
      </div>
    </QueryClientProvider>
  );

  await waitFor(() => expect(mockFetch).toHaveBeenCalled());
});

🐛 Troubleshooting​

Calendar tidak tampil​

Solution: Set explicit height pada container

Events tidak muncul​

Solution: Check API response format (id, title, start, end required)

Import error​

Solution: Update tsconfig.json atau use relative imports

Lihat Installation Guide untuk troubleshooting lengkap!

📖 Documentation Structure​

docs/
├── README.md                       # File ini (overview)
├── calendar-component.md           # Full documentation
├── calendar-installation.md        # Installation guide
├── calendar-best-practices.md      # Best practices & tips
└── calendar-quick-reference.md     # Cheatsheet

🔗 Related Resources​

📝 Version History​

v2.0.0 (Current)​

  • ✅ GenericCalendar dengan full TypeScript support
  • ✅ React Query v5 integration
  • ✅ Improved time window API
  • ✅ Better error handling
  • ✅ Comprehensive documentation

v1.0.0 (Legacy)​

  • Basic calendar dengan query key
  • Limited TypeScript support
  • See index.tsx for legacy implementation

🤝 Contributing​

Jika ingin menambahkan fitur atau improve documentation:

  1. Update component source code
  2. Update types di types.ts
  3. Update dokumentasi yang relevan:
    • API changes → calendar-component.md
    • Setup changes → calendar-installation.md
    • New patterns → calendar-best-practices.md
    • Quick snippets → calendar-quick-reference.md
  4. Add examples
  5. Update this README if needed

💬 Support​

Jika ada pertanyaan:

  1. 📖 Check dokumentasi (4 files di atas)
  2. 🔍 Search di source code
  3. 🧪 Review test examples
  4. 💡 Check best practices
  5. 📞 Contact maintainer

📄 License​

Component ini adalah bagian dari project Sisappra internal. Silakan disesuaikan dengan kebutuhan project Anda.

✨ Quick Links​

Happy Coding! 🎉

Last updated: December 5, 2025
Maintainer: Sisappra Development Team