libra/docs/stories/story-3.3-availability-calendar-display.md

Story 3.3: Availability Calendar Display

Epic Reference

Epic 3: Booking & Consultation System

User Story

As a client, I want to see a calendar with available time slots, So that I can choose a convenient time for my consultation.

Story Context

Existing System Integration

• Integrates with: working_hours, blocked_times, consultations tables
• Technology: Livewire Volt, JavaScript calendar library
• Follows pattern: Real-time availability checking
• Touch points: Booking submission flow

Acceptance Criteria

Calendar Display

• Monthly calendar view showing available dates
• Visual distinction for date states:
  • Available (has open slots)
  • Partially available (some slots taken)
  • Unavailable (fully booked or blocked)
  • Past dates (grayed out)
• Navigate between months
• Current month shown by default

Time Slot Display

• Clicking a date shows available time slots
• 1-hour slots (45min consultation + 15min buffer)
• Clear indication of slot availability
• Unavailable reasons (optional):
  • Already booked
  • Outside working hours
  • Blocked by admin

Real-time Updates

• Availability checked on date selection
• Prevent double-booking (race condition handling)
• Refresh availability when navigating months

Navigation Constraints

• Prevent navigating to months before current month (all dates would be "past")
• Optionally limit future navigation (e.g., max 3 months ahead) - configurable

Responsive Design

• Mobile-friendly calendar
• Touch-friendly slot selection
• Proper RTL support for Arabic

Quality Requirements

• Fast loading (eager load data)
• Language-appropriate date formatting
• Accessible (keyboard navigation)
• Tests for availability logic

Technical Notes

File Structure

Create the following files:

• app/Services/AvailabilityService.php - Core availability logic
• resources/views/livewire/availability-calendar.blade.php - Volt component
• lang/en/calendar.php - English calendar translations
• lang/ar/calendar.php - Arabic calendar translations
• lang/en/booking.php - English booking translations (if not exists)
• lang/ar/booking.php - Arabic booking translations (if not exists)
• tests/Unit/Services/AvailabilityServiceTest.php - Unit tests
• tests/Feature/Livewire/AvailabilityCalendarTest.php - Feature tests

Availability Service

<?php

namespace App\Services;

use App\Models\{WorkingHour, BlockedTime, Consultation};
use Carbon\Carbon;

class AvailabilityService
{
    public function getMonthAvailability(int $year, int $month): array
    {
        $startOfMonth = Carbon::create($year, $month, 1)->startOfMonth();
        $endOfMonth = $startOfMonth->copy()->endOfMonth();

        $availability = [];
        $current = $startOfMonth->copy();

        while ($current->lte($endOfMonth)) {
            $availability[$current->format('Y-m-d')] = $this->getDateStatus($current);
            $current->addDay();
        }

        return $availability;
    }

    public function getDateStatus(Carbon $date): string
    {
        // Past date
        if ($date->lt(today())) {
            return 'past';
        }

        // Check if fully blocked
        if ($this->isDateFullyBlocked($date)) {
            return 'blocked';
        }

        // Check working hours
        $workingHour = WorkingHour::where('day_of_week', $date->dayOfWeek)
            ->where('is_active', true)
            ->first();

        if (!$workingHour) {
            return 'closed';
        }

        // Get available slots
        $availableSlots = $this->getAvailableSlots($date);

        if (empty($availableSlots)) {
            return 'full';
        }

        $totalSlots = count($workingHour->getSlots(60));
        if (count($availableSlots) < $totalSlots) {
            return 'partial';
        }

        return 'available';
    }

    public function getAvailableSlots(Carbon $date): array
    {
        $workingHour = WorkingHour::where('day_of_week', $date->dayOfWeek)
            ->where('is_active', true)
            ->first();

        if (!$workingHour) {
            return [];
        }

        // All possible slots
        $allSlots = $workingHour->getSlots(60);

        // Booked slots
        $bookedSlots = Consultation::where('scheduled_date', $date->toDateString())
            ->whereIn('status', ['pending', 'approved'])
            ->pluck('scheduled_time')
            ->map(fn($t) => Carbon::parse($t)->format('H:i'))
            ->toArray();

        // Blocked slots
        $blockedSlots = $this->getBlockedSlots($date);

        return array_values(array_diff($allSlots, $bookedSlots, $blockedSlots));
    }

    private function getBlockedSlots(Carbon $date): array
    {
        $blockedTimes = BlockedTime::where('block_date', $date->toDateString())->get();
        $blockedSlots = [];

        foreach ($blockedTimes as $blocked) {
            if ($blocked->isAllDay()) {
                // Block all slots
                $workingHour = WorkingHour::where('day_of_week', $date->dayOfWeek)->first();
                return $workingHour ? $workingHour->getSlots(60) : [];
            }

            // Calculate blocked slots from time range
            $start = Carbon::parse($blocked->start_time);
            $end = Carbon::parse($blocked->end_time);
            $current = $start->copy();

            while ($current->lt($end)) {
                $blockedSlots[] = $current->format('H:i');
                $current->addMinutes(60);
            }
        }

        return array_unique($blockedSlots);
    }

    private function isDateFullyBlocked(Carbon $date): bool
    {
        return BlockedTime::where('block_date', $date->toDateString())
            ->whereNull('start_time')
            ->exists();
    }
}

Volt Component

<?php

use App\Services\AvailabilityService;
use Livewire\Volt\Component;
use Carbon\Carbon;

new class extends Component {
    public int $year;
    public int $month;
    public ?string $selectedDate = null;
    public array $monthAvailability = [];
    public array $availableSlots = [];

    public function mount(): void
    {
        $this->year = now()->year;
        $this->month = now()->month;
        $this->loadMonthAvailability();
    }

    public function loadMonthAvailability(): void
    {
        $service = app(AvailabilityService::class);
        $this->monthAvailability = $service->getMonthAvailability($this->year, $this->month);
    }

    public function previousMonth(): void
    {
        $date = Carbon::create($this->year, $this->month, 1)->subMonth();

        // Prevent navigating to past months
        if ($date->lt(now()->startOfMonth())) {
            return;
        }

        $this->year = $date->year;
        $this->month = $date->month;
        $this->selectedDate = null;
        $this->availableSlots = [];
        $this->loadMonthAvailability();
    }

    public function nextMonth(): void
    {
        $date = Carbon::create($this->year, $this->month, 1)->addMonth();
        $this->year = $date->year;
        $this->month = $date->month;
        $this->selectedDate = null;
        $this->availableSlots = [];
        $this->loadMonthAvailability();
    }

    public function selectDate(string $date): void
    {
        $status = $this->monthAvailability[$date] ?? 'unavailable';

        if (in_array($status, ['available', 'partial'])) {
            $this->selectedDate = $date;
            $this->loadAvailableSlots();
        }
    }

    public function loadAvailableSlots(): void
    {
        if (!$this->selectedDate) {
            $this->availableSlots = [];
            return;
        }

        $service = app(AvailabilityService::class);
        $this->availableSlots = $service->getAvailableSlots(
            Carbon::parse($this->selectedDate)
        );
    }

    public function with(): array
    {
        return [
            'monthName' => Carbon::create($this->year, $this->month, 1)->translatedFormat('F Y'),
            'calendarDays' => $this->buildCalendarDays(),
        ];
    }

    private function buildCalendarDays(): array
    {
        $firstDay = Carbon::create($this->year, $this->month, 1);
        $lastDay = $firstDay->copy()->endOfMonth();

        // Pad start of month
        $startPadding = $firstDay->dayOfWeek;
        $days = array_fill(0, $startPadding, null);

        // Fill month days
        $current = $firstDay->copy();
        while ($current->lte($lastDay)) {
            $dateStr = $current->format('Y-m-d');
            $days[] = [
                'date' => $dateStr,
                'day' => $current->day,
                'status' => $this->monthAvailability[$dateStr] ?? 'unavailable',
            ];
            $current->addDay();
        }

        return $days;
    }
};

Blade Template

<div>
    <!-- Calendar Header -->
    <div class="flex items-center justify-between mb-4">
        <flux:button size="sm" wire:click="previousMonth">
            <flux:icon name="chevron-{{ app()->getLocale() === 'ar' ? 'right' : 'left' }}" />
        </flux:button>

        <flux:heading size="lg">{{ $monthName }}</flux:heading>

        <flux:button size="sm" wire:click="nextMonth">
            <flux:icon name="chevron-{{ app()->getLocale() === 'ar' ? 'left' : 'right' }}" />
        </flux:button>
    </div>

    <!-- Day Headers -->
    <div class="grid grid-cols-7 gap-1 mb-2">
        @foreach(['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as $day)
            <div class="text-center text-sm font-semibold text-charcoal">
                {{ __("calendar.{$day}") }}
            </div>
        @endforeach
    </div>

    <!-- Calendar Grid -->
    <div class="grid grid-cols-7 gap-1">
        @foreach($calendarDays as $dayData)
            @if($dayData === null)
                <div class="h-12"></div>
            @else
                <button
                    wire:click="selectDate('{{ $dayData['date'] }}')"
                    @class([
                        'h-12 rounded-lg text-center transition-colors',
                        'bg-success/20 text-success hover:bg-success/30' => $dayData['status'] === 'available',
                        'bg-warning/20 text-warning hover:bg-warning/30' => $dayData['status'] === 'partial',
                        'bg-charcoal/10 text-charcoal/50 cursor-not-allowed' => in_array($dayData['status'], ['past', 'closed', 'blocked', 'full']),
                        'ring-2 ring-gold' => $selectedDate === $dayData['date'],
                    ])
                    @disabled(in_array($dayData['status'], ['past', 'closed', 'blocked', 'full']))
                >
                    {{ $dayData['day'] }}
                </button>
            @endif
        @endforeach
    </div>

    <!-- Time Slots -->
    @if($selectedDate)
        <div class="mt-6">
            <flux:heading size="sm" class="mb-3">
                {{ __('booking.available_times') }} -
                {{ \Carbon\Carbon::parse($selectedDate)->translatedFormat('d M Y') }}
            </flux:heading>

            @if(count($availableSlots) > 0)
                <div class="grid grid-cols-3 sm:grid-cols-4 gap-2">
                    @foreach($availableSlots as $slot)
                        <button
                            wire:click="$parent.selectSlot('{{ $selectedDate }}', '{{ $slot }}')"
                            class="p-3 rounded-lg border border-gold text-gold hover:bg-gold hover:text-navy transition-colors"
                        >
                            {{ \Carbon\Carbon::parse($slot)->format('g:i A') }}
                        </button>
                    @endforeach
                </div>
            @else
                <p class="text-charcoal/70">{{ __('booking.no_slots_available') }}</p>
            @endif
        </div>
    @endif

    <!-- Legend -->
    <div class="flex gap-4 mt-6 text-sm">
        <div class="flex items-center gap-2">
            <div class="w-4 h-4 rounded bg-success/20"></div>
            <span>{{ __('booking.available') }}</span>
        </div>
        <div class="flex items-center gap-2">
            <div class="w-4 h-4 rounded bg-warning/20"></div>
            <span>{{ __('booking.partial') }}</span>
        </div>
        <div class="flex items-center gap-2">
            <div class="w-4 h-4 rounded bg-charcoal/10"></div>
            <span>{{ __('booking.unavailable') }}</span>
        </div>
    </div>
</div>

RTL Support Implementation

The calendar requires specific RTL handling for Arabic users:

1. Navigation arrows: Already handled with locale-aware chevron direction (see Blade template)

2. Day headers order: Use locale-aware day ordering:

// In Volt component
private function getDayHeaders(): array
{
    $days = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];

    // Arabic calendar traditionally starts on Saturday
    if (app()->getLocale() === 'ar') {
        // Reorder: Sat, Sun, Mon, Tue, Wed, Thu, Fri
        array_unshift($days, array_pop($days));
    }

    return $days;
}

3. Calendar grid direction: Apply RTL class to the grid container:

<div class="grid grid-cols-7 gap-1" dir="{{ app()->getLocale() === 'ar' ? 'rtl' : 'ltr' }}">

4. Required translation keys (add to lang/ar/calendar.php and lang/en/calendar.php):

// lang/en/calendar.php
return [
    'Sun' => 'Sun',
    'Mon' => 'Mon',
    'Tue' => 'Tue',
    'Wed' => 'Wed',
    'Thu' => 'Thu',
    'Fri' => 'Fri',
    'Sat' => 'Sat',
];

// lang/ar/calendar.php
return [
    'Sun' => 'أحد',
    'Mon' => 'إثن',
    'Tue' => 'ثلا',
    'Wed' => 'أرب',
    'Thu' => 'خمي',
    'Fri' => 'جمع',
    'Sat' => 'سبت',
];

5. Booking translation keys (add to lang/*/booking.php):

// lang/en/booking.php
return [
    'available' => 'Available',
    'partial' => 'Partial',
    'unavailable' => 'Unavailable',
    'available_times' => 'Available Times',
    'no_slots_available' => 'No slots available for this date.',
];

// lang/ar/booking.php
return [
    'available' => 'متاح',
    'partial' => 'متاح جزئياً',
    'unavailable' => 'غير متاح',
    'available_times' => 'الأوقات المتاحة',
    'no_slots_available' => 'لا توجد مواعيد متاحة لهذا التاريخ.',
];

Definition of Done

• Calendar displays current month
• Can navigate between months
• Available dates clearly indicated
• Clicking date shows time slots
• Time slots in 1-hour increments
• Prevents selecting unavailable dates/times
• Real-time availability updates
• Mobile responsive
• RTL support for Arabic
• Tests for availability logic
• Code formatted with Pint

Testing Scenarios

AvailabilityService Unit Tests

Create tests/Unit/Services/AvailabilityServiceTest.php:

<?php

use App\Models\{WorkingHour, BlockedTime, Consultation};
use App\Services\AvailabilityService;
use Carbon\Carbon;

beforeEach(function () {
    // Setup default working hours (Monday-Friday, 9am-5pm)
    foreach ([1, 2, 3, 4, 5] as $day) {
        WorkingHour::factory()->create([
            'day_of_week' => $day,
            'start_time' => '09:00',
            'end_time' => '17:00',
            'is_active' => true,
        ]);
    }
});

describe('getDateStatus', function () {
    it('returns "past" for yesterday', function () {
        $service = new AvailabilityService();
        $yesterday = Carbon::yesterday();

        expect($service->getDateStatus($yesterday))->toBe('past');
    });

    it('returns "closed" for non-working days (weekends)', function () {
        $service = new AvailabilityService();
        $sunday = Carbon::now()->next(Carbon::SUNDAY);

        expect($service->getDateStatus($sunday))->toBe('closed');
    });

    it('returns "blocked" for fully blocked date', function () {
        $monday = Carbon::now()->next(Carbon::MONDAY);
        BlockedTime::factory()->create([
            'block_date' => $monday->toDateString(),
            'start_time' => null, // All day block
            'end_time' => null,
        ]);

        $service = new AvailabilityService();

        expect($service->getDateStatus($monday))->toBe('blocked');
    });

    it('returns "full" when all slots are booked', function () {
        $monday = Carbon::now()->next(Carbon::MONDAY);
        $slots = ['09:00', '10:00', '11:00', '12:00', '13:00', '14:00', '15:00', '16:00'];

        foreach ($slots as $slot) {
            Consultation::factory()->create([
                'scheduled_date' => $monday->toDateString(),
                'scheduled_time' => $slot,
                'status' => 'approved',
            ]);
        }

        $service = new AvailabilityService();

        expect($service->getDateStatus($monday))->toBe('full');
    });

    it('returns "partial" when some slots are booked', function () {
        $monday = Carbon::now()->next(Carbon::MONDAY);
        Consultation::factory()->create([
            'scheduled_date' => $monday->toDateString(),
            'scheduled_time' => '10:00',
            'status' => 'approved',
        ]);

        $service = new AvailabilityService();

        expect($service->getDateStatus($monday))->toBe('partial');
    });

    it('returns "available" for working day with no bookings', function () {
        $monday = Carbon::now()->next(Carbon::MONDAY);
        $service = new AvailabilityService();

        expect($service->getDateStatus($monday))->toBe('available');
    });
});

describe('getAvailableSlots', function () {
    it('returns empty array for non-working days', function () {
        $service = new AvailabilityService();
        $sunday = Carbon::now()->next(Carbon::SUNDAY);

        expect($service->getAvailableSlots($sunday))->toBe([]);
    });

    it('excludes booked consultation times', function () {
        $monday = Carbon::now()->next(Carbon::MONDAY);
        Consultation::factory()->create([
            'scheduled_date' => $monday->toDateString(),
            'scheduled_time' => '10:00',
            'status' => 'pending',
        ]);

        $service = new AvailabilityService();
        $slots = $service->getAvailableSlots($monday);

        expect($slots)->not->toContain('10:00');
    });

    it('excludes blocked time ranges', function () {
        $monday = Carbon::now()->next(Carbon::MONDAY);
        BlockedTime::factory()->create([
            'block_date' => $monday->toDateString(),
            'start_time' => '14:00',
            'end_time' => '16:00',
        ]);

        $service = new AvailabilityService();
        $slots = $service->getAvailableSlots($monday);

        expect($slots)->not->toContain('14:00');
        expect($slots)->not->toContain('15:00');
    });

    it('includes pending and approved consultations as booked', function () {
        $monday = Carbon::now()->next(Carbon::MONDAY);

        Consultation::factory()->create([
            'scheduled_date' => $monday->toDateString(),
            'scheduled_time' => '09:00',
            'status' => 'pending',
        ]);

        Consultation::factory()->create([
            'scheduled_date' => $monday->toDateString(),
            'scheduled_time' => '10:00',
            'status' => 'approved',
        ]);

        // Cancelled should NOT block the slot
        Consultation::factory()->create([
            'scheduled_date' => $monday->toDateString(),
            'scheduled_time' => '11:00',
            'status' => 'cancelled',
        ]);

        $service = new AvailabilityService();
        $slots = $service->getAvailableSlots($monday);

        expect($slots)->not->toContain('09:00');
        expect($slots)->not->toContain('10:00');
        expect($slots)->toContain('11:00'); // Cancelled slot is available
    });
});

describe('getMonthAvailability', function () {
    it('returns status for every day in the month', function () {
        $service = new AvailabilityService();
        $availability = $service->getMonthAvailability(2025, 1);

        expect($availability)->toHaveCount(31); // January has 31 days
    });

    it('handles year rollover correctly (December to January)', function () {
        $service = new AvailabilityService();

        $december = $service->getMonthAvailability(2024, 12);
        $january = $service->getMonthAvailability(2025, 1);

        expect($december)->toHaveKey('2024-12-31');
        expect($january)->toHaveKey('2025-01-01');
    });
});

Volt Component Feature Tests

Create tests/Feature/Livewire/AvailabilityCalendarTest.php:

<?php

use App\Models\{WorkingHour, BlockedTime, Consultation, User};
use Livewire\Volt\Volt;
use Carbon\Carbon;

beforeEach(function () {
    // Setup working hours for weekdays
    foreach ([1, 2, 3, 4, 5] as $day) {
        WorkingHour::factory()->create([
            'day_of_week' => $day,
            'start_time' => '09:00',
            'end_time' => '17:00',
            'is_active' => true,
        ]);
    }
});

it('displays current month by default', function () {
    $currentMonth = now()->translatedFormat('F Y');

    Volt::test('availability-calendar')
        ->assertSee($currentMonth);
});

it('navigates to next month', function () {
    $nextMonth = now()->addMonth()->translatedFormat('F Y');

    Volt::test('availability-calendar')
        ->call('nextMonth')
        ->assertSee($nextMonth);
});

it('navigates to previous month', function () {
    $prevMonth = now()->subMonth()->translatedFormat('F Y');

    Volt::test('availability-calendar')
        ->call('previousMonth')
        ->assertSee($prevMonth);
});

it('handles year rollover when navigating months', function () {
    // Start in December
    Carbon::setTestNow(Carbon::create(2024, 12, 15));

    Volt::test('availability-calendar')
        ->assertSet('year', 2024)
        ->assertSet('month', 12)
        ->call('nextMonth')
        ->assertSet('year', 2025)
        ->assertSet('month', 1);

    Carbon::setTestNow();
});

it('loads available slots when date is selected', function () {
    $monday = Carbon::now()->next(Carbon::MONDAY)->format('Y-m-d');

    Volt::test('availability-calendar')
        ->call('selectDate', $monday)
        ->assertSet('selectedDate', $monday)
        ->assertNotEmpty('availableSlots');
});

it('does not select unavailable dates', function () {
    $sunday = Carbon::now()->next(Carbon::SUNDAY)->format('Y-m-d');

    Volt::test('availability-calendar')
        ->call('selectDate', $sunday)
        ->assertSet('selectedDate', null)
        ->assertSet('availableSlots', []);
});

it('clears selection when navigating months', function () {
    $monday = Carbon::now()->next(Carbon::MONDAY)->format('Y-m-d');

    Volt::test('availability-calendar')
        ->call('selectDate', $monday)
        ->assertSet('selectedDate', $monday)
        ->call('nextMonth')
        ->assertSet('selectedDate', null)
        ->assertSet('availableSlots', []);
});

it('displays RTL layout for Arabic locale', function () {
    app()->setLocale('ar');

    Volt::test('availability-calendar')
        ->assertSeeHtml('dir="rtl"');
});

it('prevents navigating to past months', function () {
    Volt::test('availability-calendar')
        ->assertSet('year', now()->year)
        ->assertSet('month', now()->month)
        ->call('previousMonth')
        ->assertSet('year', now()->year) // Should not change
        ->assertSet('month', now()->month); // Should not change
});

Browser Tests (Optional - Story 3.4+ integration)

<?php

use App\Models\{WorkingHour, User};

it('allows selecting a time slot with mouse click', function () {
    // Setup working hours
    WorkingHour::factory()->create([
        'day_of_week' => Carbon::MONDAY,
        'is_active' => true,
    ]);

    $user = User::factory()->create();

    $page = visit('/book')
        ->actingAs($user)
        ->assertSee('Available')
        ->click('[data-available-date]')
        ->assertSee('Available Times')
        ->click('[data-time-slot="09:00"]')
        ->assertNoJavascriptErrors();
});

Dependencies

• Story 3.1: Working hours (defines available time) - MUST be completed first
• Story 3.2: Blocked times (removes availability) - MUST be completed first
• Story 3.4: Booking submission (consumes selected slot) - developed after this story

Parent Component Dependency

This calendar component is designed to be embedded within a parent booking component (Story 3.4). The $parent.selectSlot() call expects the parent to have a selectSlot(string $date, string $time) method. For standalone testing, create a wrapper component or mock the parent interaction.

Risk Assessment

• Primary Risk: Race condition on slot selection
• Mitigation: Database-level unique constraint, check on submission
• Rollback: Refresh availability if booking fails

Race Condition Prevention Strategy

The calendar display component itself does not handle booking submission - that is Story 3.4's responsibility. However, this story must support race condition prevention by:

1. Fresh availability check on date selection: Always reload slots when a date is clicked (already implemented in loadAvailableSlots())

2. Database constraint (to be added in Story 3.4 migration):

// In consultations table migration
$table->unique(['scheduled_date', 'scheduled_time'], 'unique_consultation_slot');

3. Optimistic UI with graceful fallback: If a slot is selected but booking fails due to race condition, the calendar should refresh availability:

// In parent booking component (Story 3.4)
public function selectSlot(string $date, string $time): void
{
    // Re-verify slot is still available before proceeding
    $service = app(AvailabilityService::class);
    $availableSlots = $service->getAvailableSlots(Carbon::parse($date));

    if (!in_array($time, $availableSlots)) {
        $this->dispatch('slot-unavailable');
        $this->loadAvailableSlots(); // Refresh the calendar
        return;
    }

    $this->selectedDate = $date;
    $this->selectedTime = $time;
}

Estimation

Complexity: High Estimated Effort: 5-6 hours