task ep1.6.1

plans/task-ep.1.6.1.md

@@ -0,0 +1,248 @@
+## Calendar Empty State Rendering Improvement
+
+**Status:** Completed
+
+### Background
+
+The current Calendar Workspace renders a full-page empty state when no Calendar events are returned.
+
+Current behavior:
+
+```text
+No scheduled work in this period
+
+Try changing filters or create an Activity from the owning CRM record.
+```
+
+This behavior is acceptable for an Agenda (list) view but is not appropriate for graphical calendar views.
+
+A calendar should remain a calendar even when there are no events.
+
+Users still need to:
+
+* understand the selected date range
+* navigate between dates
+* visualize available time slots
+* click an empty day or time slot
+* create a new Activity
+* understand that the schedule is empty rather than the Calendar failing
+
+---
+
+## Required UX Change
+
+### Day View
+
+Always render the complete Calendar grid.
+
+When there are no events:
+
+* render the timeline/grid normally
+* show an inline empty-state hint inside the calendar body
+* keep toolbar, navigation, and date controls visible
+* allow selecting a time slot
+* allow creating a new Activity
+
+Do **NOT** replace the Calendar with a full-page empty screen.
+
+---
+
+### Week View
+
+Always render the Week grid.
+
+When there are no events:
+
+* render all days
+* render working hours
+* render current time indicator where applicable
+* render an inline empty hint only
+* preserve drag target areas for future Activity creation
+
+Do **NOT** hide the calendar grid.
+
+---
+
+### Month View
+
+Always render the Month calendar.
+
+When there are no events:
+
+* render the entire month
+* render all weeks
+* render date cells
+* render navigation
+* optionally display a small "No events" message inside the month body
+
+The Month view should always look like a usable calendar.
+
+---
+
+### Agenda View
+
+Agenda is different.
+
+Agenda is a list-based presentation.
+
+When there are no scheduled items:
+
+Show the existing empty state:
+
+```text
+No scheduled work in this period.
+
+Try changing filters or create an Activity.
+```
+
+This behavior remains correct.
+
+---
+
+## Rendering Rules
+
+Preferred rendering logic:
+
+```text
+Day
+    ↓
+Always render Calendar Grid
+
+Week
+    ↓
+Always render Calendar Grid
+
+Month
+    ↓
+Always render Calendar Grid
+
+Agenda
+    ↓
+If empty
+    Show Empty State
+Else
+    Show Agenda List
+```
+
+The Calendar component should never disappear simply because there are zero events.
+
+---
+
+## Empty Calendar Overlay
+
+Instead of replacing the Calendar component, render a lightweight overlay or inline message.
+
+Example:
+
+```text
+──────────────────────────────
+
+        No scheduled work
+
+     Your schedule is free.
+
+      [+ Add Activity]
+
+──────────────────────────────
+```
+
+The overlay must not block:
+
+* changing dates
+* changing view
+* selecting days
+* selecting time slots
+* opening filters
+
+---
+
+## Add Activity Entry Point
+
+When the Calendar contains no events, provide a visible primary action:
+
+```text
++ Add Activity
+```
+
+The button must reuse the existing Activity form and Activity API.
+
+Do not introduce a Calendar-specific create flow.
+
+---
+
+## Calendar Interaction
+
+Even when empty, users must still be able to:
+
+* navigate month/week/day
+* click a date
+* click a time slot
+* switch views
+* change filters
+* search
+* create Activities
+
+The Calendar should remain fully interactive.
+
+---
+
+## Big Calendar Integration
+
+Because the project uses **lramos33/big-calendar** as the UI foundation:
+
+* always render the Big Calendar component for Day, Week, and Month
+* pass an empty event array when appropriate
+* never short-circuit rendering based on `events.length === 0`
+* use the Calendar's native layout even when there are no events
+
+Avoid patterns such as:
+
+```tsx
+if (events.length === 0) {
+  return <CalendarEmptyState />;
+}
+```
+
+Instead:
+
+```tsx
+<BigCalendar events={events} />
+
+{events.length === 0 && view === "agenda" && (
+  <AgendaEmptyState />
+)}
+
+{events.length === 0 && view !== "agenda" && (
+  <CalendarEmptyOverlay />
+)}
+```
+
+---
+
+## UX Principles
+
+The Calendar is a navigation surface, not only an event list.
+
+Users should always understand:
+
+* where they are
+* which dates are visible
+* which time slots are available
+* where new Activities can be scheduled
+
+An empty schedule should feel like available capacity—not like a missing screen.
+
+---
+
+## Acceptance Criteria
+
+* Day view always renders the calendar grid.
+* Week view always renders the calendar grid.
+* Month view always renders the calendar grid.
+* Agenda keeps the existing list-style empty state.
+* Empty Day/Week/Month views display a lightweight overlay instead of replacing the Calendar.
+* Calendar navigation remains available when no events exist.
+* Date and time slots remain clickable.
+* Users can create Activities directly from an empty calendar.
+* No full-page empty state is shown for Day, Week, or Month views.
+* The implementation remains compatible with `lramos33/big-calendar` and ALLA OS projection architecture.