600 lines
7.7 KiB
Markdown
600 lines
7.7 KiB
Markdown
# 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.
|