commit task-ep.1.6.2-r1

plans/task-ep.1.6.2.md

@@ -0,0 +1,599 @@
+# Task EP.1.6.2 – Direct Big Calendar UI Adoption
+
+**Status:** Foundation Implemented
+
+**Priority:** High
+
+**Type:** UI Modernization / Calendar UX / Frontend Refactor
+
+---
+
+# Depends On
+
+* EP.1.6 Calendar Projection, Workspace & Big Calendar Foundation
+* EP.1.6.1 Calendar Empty State Rendering Improvement
+* EP.1.7 My Day Workspace Foundation
+
+---
+
+# Objective
+
+Replace the current custom Calendar UI implementation with the original **lramos33/big-calendar** component architecture while preserving the ALLA OS backend architecture.
+
+This task is **UI-only**.
+
+No business logic, projection model, Activity ownership, Business Events, or Calendar Projection architecture shall change.
+
+---
+
+# Background
+
+EP.1.6 successfully introduced:
+
+* Calendar Projection
+* Calendar Query Service
+* Calendar Workspace
+* Calendar Projection Runtime
+* Activity integration
+* Calendar API
+* Calendar security
+
+However the current UI only references the upstream project conceptually.
+
+It does **NOT** use the original Calendar UI implementation.
+
+The goal of EP.1.6.2 is to adopt the upstream Calendar components directly so ALLA OS gains the same interaction quality and polished UX.
+
+---
+
+# Review Required
+
+Review before implementation:
+
+* AGENTS.md
+* LAYOUT.md
+* ui-ux-rules.md
+* Engineering Constitution
+* EP.1.6
+* EP.1.6.1
+* EP.1.7
+
+Review upstream project:
+
+```text
+https://github.com/lramos33/big-calendar
+```
+
+Review:
+
+* component structure
+* provider architecture
+* drag & drop
+* resize
+* agenda
+* month
+* week
+* day
+* year
+* event rendering
+* toolbar
+* filters
+* responsive behavior
+* dark mode
+
+---
+
+# Architecture Principle
+
+ALLA OS owns:
+
+* Activity
+* Calendar Projection
+* Business Events
+* Projection Runtime
+* Permissions
+* APIs
+
+Big Calendar owns:
+
+* Calendar rendering
+* Calendar interactions
+* View switching
+* Event layout
+* Drag UX
+* Resize UX
+* Toolbar
+* Navigation
+
+---
+
+# Data Flow
+
+Must remain
+
+```text
+Activity
+
+↓
+
+Business Event
+
+↓
+
+Projection Runtime
+
+↓
+
+crm_calendar_projection
+
+↓
+
+CalendarProjectionItem
+
+↓
+
+Calendar Adapter
+
+↓
+
+Big Calendar Components
+```
+
+No upstream component may read database rows directly.
+
+---
+
+# Scope
+
+---
+
+# Part 1 — Direct Component Adoption
+
+Adopt upstream source components directly.
+
+Do NOT recreate:
+
+* Month Grid
+* Week Grid
+* Day Grid
+* Agenda Layout
+* Calendar Header
+* Calendar Navigation
+
+Use upstream implementation instead.
+
+---
+
+# Part 2 — Remove Custom Calendar Rendering
+
+Deprecate current custom:
+
+* Day
+* Week
+* Month
+
+renderers.
+
+Only keep:
+
+* ALLA adapter
+* wrapper
+* permissions
+* Activity actions
+
+---
+
+# Part 3 — Calendar Provider
+
+Introduce upstream provider.
+
+Wrap ALLA Calendar.
+
+The provider receives
+
+CalendarProjectionItem
+
+through an adapter.
+
+---
+
+# Part 4 — Adapter Layer
+
+Implement
+
+```ts
+mapCalendarProjectionToBigCalendarEvent()
+```
+
+and
+
+```ts
+mapBigCalendarActionToActivityCommand()
+```
+
+No business logic inside UI.
+
+---
+
+# Part 5 — Toolbar Integration
+
+Use upstream toolbar.
+
+Adapt:
+
+* Today
+* Previous
+* Next
+* Date Picker
+* View Selector
+
+Integrate with:
+
+* URL search params
+* React Query
+
+---
+
+# Part 6 — View Integration
+
+Support
+
+* Day
+* Week
+* Month
+* Agenda
+
+Optional
+
+* Year
+
+Do not change upstream layout unnecessarily.
+
+---
+
+# Part 7 — Event Rendering
+
+Differentiate
+
+Editable Activity
+
+vs
+
+Read-only Milestone
+
+Show
+
+* icon
+* badge
+* customer
+* title
+* priority
+* overdue
+* Hot Project
+
+using ALLA adapter.
+
+---
+
+# Part 8 — Drag & Drop
+
+Enable upstream drag.
+
+Rules
+
+Editable
+
+↓
+
+Activity API
+
+↓
+
+Business Event
+
+↓
+
+Projection Refresh
+
+Read-only milestones
+
+↓
+
+cannot move.
+
+---
+
+# Part 9 — Resize
+
+Enable resize.
+
+Only
+
+Activity
+
+may resize.
+
+Never
+
+Milestones.
+
+---
+
+# Part 10 — Event Detail
+
+Selecting an event opens
+
+ALLA Activity Sheet
+
+or
+
+Source Detail Sheet
+
+depending on
+
+Activity
+
+or
+
+Milestone.
+
+---
+
+# Part 11 — Working Hours
+
+Reuse upstream configuration.
+
+Default
+
+Asia/Bangkok
+
+Support
+
+Organization setting
+
+Future
+
+User preference.
+
+---
+
+# Part 12 — Current Time
+
+Enable
+
+Now Indicator
+
+from upstream.
+
+---
+
+# Part 13 — Today Highlight
+
+Use upstream
+
+Today
+
+highlight behavior.
+
+---
+
+# Part 14 — User Filter
+
+Replace upstream demo users.
+
+Use
+
+CRM Users API
+
+Permission aware.
+
+---
+
+# Part 15 — Theme Integration
+
+Align
+
+fonts
+
+spacing
+
+cards
+
+buttons
+
+badges
+
+colors
+
+with ALLA OS.
+
+Avoid redesigning upstream.
+
+---
+
+# Part 16 — Responsive Review
+
+Validate
+
+Desktop
+
+Tablet
+
+Mobile
+
+Agenda remains mobile default.
+
+---
+
+# Part 17 — Accessibility
+
+Validate
+
+* keyboard
+* focus
+* screen reader
+* contrast
+* dark mode
+
+---
+
+# Part 18 — Calendar Empty State
+
+Keep
+
+EP.1.6.1 behavior.
+
+Day
+
+Week
+
+Month
+
+↓
+
+render calendar.
+
+Agenda
+
+↓
+
+render empty list.
+
+---
+
+# Part 19 — Source Audit
+
+Document
+
+* adopted files
+* modified files
+* untouched files
+* removed demo code
+
+---
+
+# Part 20 — Upgrade Strategy
+
+Record
+
+* upstream commit hash
+* version reviewed
+* local patches
+* synchronization strategy
+
+Future updates must be traceable.
+
+---
+
+# Part 21 — Performance
+
+Verify
+
+* Month rendering
+* Week rendering
+* Day rendering
+* Agenda rendering
+* Virtualization where applicable
+* React re-render counts
+* Lazy event loading
+
+---
+
+# Part 22 — Regression Testing
+
+Verify
+
+Calendar
+
+does not break
+
+* Activity
+* Timeline
+* Dashboard
+* My Day
+* Projection Runtime
+* Permission model
+
+---
+
+# Deliverables
+
+1. Direct Big Calendar integration
+2. Calendar Provider
+3. Calendar Adapter Layer
+4. Toolbar Integration
+5. Day View
+6. Week View
+7. Month View
+8. Agenda View
+9. Optional Year View
+10. Drag & Drop
+11. Resize
+12. Current Time Indicator
+13. Today Highlight
+14. User Filter
+15. Theme Integration
+16. Responsive Review
+17. Accessibility Review
+18. Source Audit Report
+19. Upgrade Strategy Document
+20. Regression Report
+
+---
+
+# Constraints
+
+Must preserve
+
+* Activity ownership
+* Calendar Projection
+* Timeline
+* Projection Runtime
+* Business Events
+* CRM permissions
+* API contracts
+
+Must NOT
+
+* replace Calendar Projection
+* introduce local event storage
+* duplicate Activity logic
+* bypass Activity API
+* bypass Business Events
+* mutate projection rows directly
+
+---
+
+# Verification
+
+* `npm run typecheck`
+* `npm run db:generate`
+* `npx oxlint src/features/crm/calendar`
+* Calendar interaction tests
+* Drag & Drop tests
+* Resize tests
+* Permission tests
+* Responsive tests
+* Accessibility tests
+
+---
+
+# Acceptance Criteria
+
+* The Calendar UI is built directly on the **lramos33/big-calendar** source components rather than custom-rendered Day, Week, and Month grids.
+* ALLA OS retains ownership of Activity, Calendar Projection, Business Events, Projection Runtime, and CRM authorization.
+* `CalendarProjectionItem` is adapted into the upstream event model through a dedicated adapter layer.
+* Upstream toolbar, navigation, Day, Week, Month, and Agenda views are reused with minimal structural modification.
+* Editable Activities support drag-and-drop and resize through the Activity API only.
+* Read-only milestones cannot be dragged or resized.
+* The current-time indicator and Today highlighting are enabled.
+* Day, Week, and Month always render the Calendar grid; Agenda retains the list-style empty state from EP.1.6.1.
+* The upstream MIT license is preserved, and an audit documents all adopted and modified source files.
+* The Calendar visually matches the upstream interaction quality while following `LAYOUT.md`, `ui-ux-rules.md`, and `ui-ux-pro-max`.
+* Existing Activity, Calendar Projection, Timeline, My Day, Dashboard, Reports, Notifications, and Projection Runtime behavior remain unchanged.
+
+---
+
+# Success Criteria
+
+ALLA OS transitions from a custom Calendar implementation to a **direct integration of the `lramos33/big-calendar` UI**, delivering a polished enterprise calendar experience while preserving the existing backend architecture, business rules, security model, and Projection-based design.