Livewire Calendar Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require caiquebispo/livewire-calendar

Publish the config (if needed):

php artisan vendor:publish --provider="CaiqueBispo\LivewireCalendar\LivewireCalendarServiceProvider" --tag="config"

2. First Usage: Add the component to a Livewire blade file:

   @livewire('calendar')
   

   Or use it directly in a Livewire component:

   use CaiqueBispo\LivewireCalendar\LivewireCalendar;
   
   public function mount() {
       $this->calendar = new LivewireCalendar();
   }
   
   public function render() {
       return view('livewire.calendar-component', [
           'calendar' => $this->calendar
       ]);
   }
   

3. Basic Configuration: Define default settings in config/livewire-calendar.php:

   'default_view' => 'month',
   'start_day' => 0, // Monday
   'locale' => 'en',
   

First Use Case: Displaying a Calendar

@livewire('calendar', [
    'view' => 'month',
    'year' => now()->year,
    'month' => now()->month,
    'events' => [
        ['date' => '2023-12-25', 'title' => 'Christmas'],
        ['date' => '2024-01-01', 'title' => 'New Year']
    ]
])

Implementation Patterns

Core Workflows

1. Event Handling

• Passing Events:

  $this->calendarEvents = [
      ['date' => '2023-12-25', 'title' => 'Christmas', 'color' => 'bg-red-500'],
      ['date' => '2023-12-31', 'title' => 'New Year\'s Eve', 'description' => 'Party time!']
  ];
  

• Dynamic Events via API:

  public function getEvents() {
      return Event::whereDate('date', '>=', $this->startDate)
                  ->whereDate('date', '<=', $this->endDate)
                  ->get(['date', 'title', 'description']);
  }
  

2. Date Selection

• Single Date Selection:

  public $selectedDate = null;
  
  public function updatedSelectedDate($date) {
      $this->selectedDate = $date;
      $this->emit('dateSelected', $date);
  }
  

• Range Selection:

  public $startDate = null;
  public $endDate = null;
  
  public function updatedStartDate($date) {
      $this->startDate = $date;
  }
  
  public function updatedEndDate($date) {
      $this->endDate = $date;
  }
  

3. View Switching

• Programmatic Navigation:

  public function nextMonth() {
      $this->year = $this->month === 12 ? $this->year + 1 : $this->year;
      $this->month = $this->month === 12 ? 1 : $this->month + 1;
  }
  
  public function previousMonth() {
      $this->year = $this->month === 1 ? $this->year - 1 : $this->year;
      $this->month = $this->month === 1 ? 12 : $this->month - 1;
  }
  

4. Customizing Appearance

• TailwindCSS Classes:

  @livewire('calendar', [
      'cell_classes' => [
          'today' => 'bg-blue-500 text-white',
          'selected' => 'bg-green-500 text-white',
          'other-month' => 'text-gray-300',
          'event' => 'bg-red-200'
      ]
  ])
  

• Custom Views: Extend the component by overriding the render method:

  public function render() {
      return view('livewire.custom-calendar', [
          'calendar' => $this->calendar,
          'customView' => true
      ]);
  }
  

5. Integration with Livewire Features

• Realtime Updates:

  protected $listeners = ['refreshEvents' => 'loadEvents'];
  
  public function loadEvents() {
      $this->calendarEvents = $this->getEventsFromDatabase();
  }
  

• Form Submission:

  public function submitSelectedDate() {
      $this->validate(['selectedDate' => 'required']);
      // Save to database
      $this->dispatch('dateSaved', $this->selectedDate);
  }
  

Advanced Patterns

1. Multi-Calendar Support

public function render() {
    return view('livewire.multi-calendar', [
        'calendars' => [
            ['id' => 'work', 'title' => 'Work Calendar', 'events' => $this->workEvents],
            ['id' => 'personal', 'title' => 'Personal Calendar', 'events' => $this->personalEvents]
        ]
    ]);
}

2. Timezone Handling

use Carbon\Carbon;

public function mount() {
    $this->timezone = config('app.timezone');
    $this->carbon = new Carbon('now', $this->timezone);
}

public function getFormattedDate($date) {
    return $this->carbon->copy()->parse($date)->format('Y-m-d');
}

3. Localization

public function mount() {
    $this->locale = app()->getLocale();
    $this->monthNames = [
        'January', 'February', 'March', 'April', 'May', 'June',
        'July', 'August', 'September', 'October', 'November', 'December'
    ];
}

4. Accessibility Enhancements

@livewire('calendar', [
    'aria_labels' => [
        'header' => 'Calendar Navigation',
        'day' => 'Day {date}',
        'month' => 'Month View',
        'year' => 'Year View'
    ]
])

Gotchas and Tips

Pitfalls and Debugging

1. Event Overlapping

• Issue: Events on the same day may not display correctly if not handled properly.
• Fix: Use z-index in Tailwind classes or ensure events are ordered by time:

  $events = Event::whereDate('date', $date)->orderBy('time')->get();
  

2. Timezone Mismatches

• Issue: Dates may appear incorrect if timezone isn't set.
• Fix: Explicitly set timezone in config or component:

  public function mount() {
      date_default_timezone_set(config('app.timezone'));
  }
  

3. Mobile Swipe Conflicts

• Issue: Swipe gestures may interfere with other mobile interactions.
• Fix: Disable swipe or adjust touch targets:

  'touch_config' => [
      'enabled' => true,
      'min_touch_distance' => 50,
      'swipe_threshold' => 0.5
  ]
  

4. Performance with Large Datasets

• Issue: Rendering many events can slow down the component.
• Fix: Lazy-load events or paginate:

  public function getEventsForMonth($year, $month) {
      return Event::whereMonth('date', $month)
                  ->whereYear('date', $year)
                  ->limit(100)
                  ->get();
  }
  

5. Livewire Wire:ignore Conflicts

• Issue: Dynamic updates may not work if elements are wrapped in @wire:ignore.
• Fix: Ensure the calendar container is not ignored:

  <div x-data="{ /* Alpine.js state */ }">
      @livewire('calendar') <!-- Not inside wire:ignore -->
  </div>
  

Configuration Quirks

1. Default View Overrides

• The default_view config may not apply if explicitly set in the component props:

  // Overrides config
  public $view = 'week';
  

2. Locale Fallback

• If the locale isn't found, it defaults to en. Ensure your locale files are published:

  php artisan vendor:publish --tag=livewire-calendar-lang
  

3. Tailwind JIT Conflicts

• Issue: Custom classes may not apply if Tailwind JIT isn't configured.
• Fix: Extend your Tailwind config:

  module.exports = {
      safelist: [
          'bg-blue-500', 'text-white', 'bg-red-200',
          // Add other dynamic classes used in the calendar
      ]
  }
  

Extension Points

1.