# Phase 2 — Shift Scheduling UX Architecture & Interactive Dashboard Plan

## 1. Executive Summary
This document defines the UX/UI plan for the redesigned Shift Schedule Management dashboard. The objective is to transition from a form-heavy administrative interface to a highly interactive, visual workspace. HR and admins will be able to instantly identify unscheduled employees, manage conflicts, approve pending changes, and perform safe bulk assignments directly from a spreadsheet-like grid, all while maintaining strict access controls and audit capabilities.

## 2. Current UI Audit
**ShiftSchedulePage.jsx & LayouSMDashboard.jsx**
- **Top Bar**: Contains Start/End date, Branch/Position dropdowns, Employee Search, Reload, Export (XLSX/PDF), and Notify Employees buttons.
- **Grid Structure**: Fixed at top, with `ScheduleBoard` rendering employees in rows and dates in columns. 
- **Pending Panel**: A permanently embedded right-side panel (`ch` in dist) taking up 450px for submissions.
- **AssignScheduleModal.jsx**: A multi-step form loop processing employees sequentially.
- **ConflicResolveModal.jsx**: Technical modal exposing raw JSON-like differences and priority options.
- **Classification**:
  - Main Filter Bar: IMPROVE (Needs better date navigation and status filters).
  - Main Grid: IMPROVE (Needs clearer cell states).
  - Pending Panel: REPLACE (Convert to a collapsible drawer or dedicated tab to save horizontal space).
  - AssignScheduleModal: REPLACE (Need a new Assignment Wizard supporting batch validation).
  - Notify All: REMOVE FROM PRIMARY VIEW (Move to an after-action step or More menu).

## 3. UX Problems
- **Sequential Bulk Assignment**: The Assign Modal loops over employees, triggering multiple conflict popups sequentially, creating a high-friction experience.
- **Space Constriction**: The 450px pending panel reduces the schedule grid width significantly on smaller desktop screens.
- **Technical Conflict UI**: Exposing priority integers and raw database concepts confuses ordinary users.
- **Missing At-a-Glance Metrics**: No quick way to see how many employees are unscheduled or have conflicts without scrolling through the grid.
- **Hidden Leave/Holiday States**: Leaves act as hidden barriers; the UI does not proactively warn the scheduler until an error occurs.

## 4. Information Hierarchy
1. **Level 1 — Needs Attention**: Unscheduled Employees, Pending Approvals, Conflicts, Missing Schedules.
2. **Level 2 — Main Schedule**: The primary interactive grid (Employee × Date).
3. **Level 3 — Supporting Information**: Leave badges, Holiday markers, Rest Day indicators, specific shift times.
4. **Level 4 — Administrative Tools**: Exports, Bulk Notifications, Audit History, Advanced Configuration.

## 5. Dashboard Layout
The dashboard will prioritize the grid while providing quick metric summaries above it.
- **Header**: Clean title and primary [+ Assign Schedule] button.
- **Summary Cards**: Interactive widgets acting as quick filters.
- **Filter Bar**: Date navigation and dropdowns.
- **Workspace**: Full-width Grid.
- **Right Drawer (Hidden by default)**: Pending Approvals, Detail Views, and Conflict Reviews.

## 6. Summary Cards
Interactive cards placed above the schedule workspace:
- **UNSCHEDULED**: Count of employee/day pairs missing a schedule. Click → Filters grid to show rows with missing schedules.
- **PENDING APPROVALS**: Count of proposed changes. Click → Opens Pending Approvals Drawer.
- **CONFLICTS**: Count of unresolved schedule conflicts. Click → Opens Exception Review queue.
- **ON LEAVE**: Count of approved leaves in the date range. Click → Highlights leave cells.

## 7. Filter & Navigation Design
- **Date Navigation**: Segmented controls for [‹] [Today] [›] [This Week] [Next Week] [14 Days] [Custom].
- **Organizational Filters**: Dropdowns for Branch, Department, Position.
- **Status Filter**: Multi-select dropdown: All, Scheduled, Unscheduled, Rest Day, Leave, Pending Change.
- **Search**: Fast text-search by employee name or ID.
- **More Filters**: Hidden by default (e.g. Employee Type).
- **Clear Filters**: A single "Reset View" button.

## 8. Schedule Grid Design
- **Employee Column**: Sticky left column. Shows Avatar (or initials), Full Name, Position, and Branch. Width: ~250px.
- **Date Headers**: Sticky top headers. Format: `MON, AUG 10`. Weekends shaded lightly. Holidays show a festive icon/badge overlay on the header.
- **Grid Layout**: Virtualized to support hundreds of rows without lag.

## 9. Schedule Cell States
- **Final Schedule**: Solid white/gray background. Dark text showing Shift Name and `09:00 - 18:00`.
- **Pending Change**: Dashed border with a small clock icon `⏱ Pending`.
- **Rest Day**: Subtle gray striped background. Text explicitly states `REST DAY`.
- **Unscheduled**: Visually distinct empty cell. Shows `+ Assign` on hover.
- **Approved Leave**: Shift text remains visible but muted, with a strong color badge overlay (e.g., solid purple/orange) stating `LEAVE: Vacation`.
- **Conflict**: Red border, strong `⚠ Conflict` label overriding the cell content.

## 10. Quick Assignment
Clicking an Unscheduled cell opens a small context menu:
**Title**: Employee Name | Date
**Actions**: 
- Select from top 3 most used shifts (e.g. Morning 9-6)
- Mark as Rest Day
- [More Options...] (Opens Assignment Wizard)
*Behavior*: If user has `schedules.manage`, immediately assigns. If user only has propose authority, creates a pending submission.

## 11. Assignment Wizard
A modal for complex assignments.
- **Step 1 - Who**: Checkbox list of filtered employees.
- **Step 2 - What**: Select Shift from rich cards showing times and break details.
- **Step 3 - When**: Single Date, Date Range, or Weekly Pattern (M T W T F S S).
- **Step 4 - Review**: English summary ("Assign Morning Shift to 10 employees for Aug 10-14"). Shows pre-assignment validation (Ready, Leaves, Conflicts).

## 12. Bulk Scheduling
- **Selection**: Spreadsheet-style checkboxes in the Employee Column and Date Headers. Range selection (Shift+Click).
- **Bulk Action Bar**: Appears floating at the bottom when cells are selected. "15 cells selected -> [Assign Shift] [Mark Rest Day] [Clear]".
- **Backend Flow**: Frontend sends a unified array to a new batch endpoint. The endpoint returns a single result object (Successes, Conflicts, Failures) rather than looping.

## 13. Conflict Review
Replaces technical JSON views with a human-readable Exception Queue drawer.
- Shows Employee, Date, Current Schedule vs Proposed Schedule.
- Actions: [Keep Existing], [Replace This Date].
- Conflicts are queued so the HR user can review them in bulk rather than receiving 50 popups.

## 14. Pending Approval UX
Moved from a permanent grid-crushing side panel to a **Collapsible Right Drawer**.
- Accessible via the "Pending Approvals" summary card or a dedicated button.
- Displays cards for each submission: Requester, Date, Employee, Old Shift -> New Shift.
- Actions: [Approve], [Reject], [Bulk Approve Selected].

## 15. Leave/Holiday/Rest Day UX
- **Leave Cell Click**: Opens Detail Popover. Shows "Scheduled: Morning 9-6", "Leave: Sick Leave (Approved)". Blocks quick assignment unless policy permits overrides.
- **Holiday**: Header indicator. The underlying schedule remains active.
- **Rest Day**: Distinct from Unscheduled. Handled as a specific state in the UI.

## 16. Historical Schedule UX
- **Future & Today (Pre-Attendance)**: Normal editing rules apply.
- **Today (Post-Attendance) & Past Dates**: Clicking triggers a `Schedule Correction` flow requiring a reason/audit note.
- **Finalized Payroll Period**: Cells are visually locked (padlock icon). Click shows "Locked by Payroll".

## 17. Mobile/Tablet UX
- **Tablet**: Normal grid, but Pending Approvals and Conflict Reviews are strictly modal/drawers to preserve touch space.
- **Mobile**: Grid is replaced by an **Agenda View**.
  - Shows an endless scroll of days.
  - Tapping a day expands to show employees scheduled.
  - Alternatively, User selects an Employee, then sees their 7-day upcoming list.
  - Advanced bulk assignments are hidden on mobile; quick singular cell changes are supported via Action Sheets.

## 18. Interaction Map
- **Click Summary Card (Unscheduled)** → UI Result: Grid filters to show only rows missing schedules → Available Actions: Use Bulk checkboxes to assign.
- **Click Empty Cell** → UI Result: Quick Assign Menu → Available Actions: Select Shift, Rest Day, More Options.
- **Click Final Schedule** → UI Result: Detail Popover → Available Actions: Change Shift, Rest Day, Copy, Replace.
- **Click Pending Cell** → UI Result: Opens Approval Drawer directly to that item → Available Actions: Approve/Reject.
- **Click Date Header** → UI Result: Selects entire column → Available Actions: Bulk Assign Bar appears.

## 19. Permission-Aware Behavior
- **Role: HR/Admin** (schedules.manage): Cell clicks show "Assign" and "Replace". Summary cards show "Pending Approvals" routing to the review queue.
- **Role: Manager** (propose only): Cell clicks show "Propose Change". "Pending Approvals" shows only their department's submissions without Approve buttons.
- **Role: Employee**: If access granted, UI restricts view to `employee_id = self`, cells show "Request Change". (Note: Out of current scope, but architecture supports it).

## 20. Component Architecture
```text
ShiftSchedulePage (Main Container)
├── ScheduleHeader (NEW - Clean title and primary actions)
├── ScheduleSummaryCards (NEW - Interactive metric widgets)
├── ScheduleToolbar (REFACTOR - Modernized filter bar)
├── ScheduleWorkspace (NEW - Wrapper for grid and drawers)
│   ├── ScheduleGrid (REFACTOR - Virtualized, cleaner cell rendering)
│   ├── ScheduleLegend (NEW - Compact persistent legend)
├── ScheduleDrawers
│   ├── PendingApprovalDrawer (REPLACE - Replaces PendingPanel)
│   ├── ConflictReviewDrawer (REPLACE - Replaces ConflicResolveModal)
│   └── ScheduleDetailDrawer (NEW - For historical/correction views)
├── QuickSchedulePopover (NEW - For fast cell clicks)
├── BulkActionBar (NEW - Floating bottom bar on selection)
└── AssignScheduleWizard (REPLACE - Replaces AssignScheduleModal)
```

## 21. ASCII Wireframes
```text
┌──────────────────────────────────────────────────────────────────────────┐
│ Shift Scheduling                                      [+ Assign Schedule]│
│ Plan, review, and manage employee schedules.                             │
├──────────────────────────────────────────────────────────────────────────┤
│ ╭─────────────╮ ╭─────────────╮ ╭─────────────╮ ╭─────────────╮          │
│ │ UNSCHEDULED │ │ PENDING (5) │ │ CONFLICTS(2)│ │ ON LEAVE (8)│          │
│ ╰─────────────╯ ╰─────────────╯ ╰─────────────╯ ╰─────────────╯          │
├──────────────────────────────────────────────────────────────────────────┤
│ ‹  [This Week]  ›  Aug 10–16                               [Reset Filters]│
│ Branch [All] Position [All] Status [All] Search [____________]          │
├──────────────────────────────────────────────────────────────────────────┤
│ Legend: ● Final  ◌ Pending  [R] Rest Day  [L] Leave  ⚠ Conflict          │
├──────────────────────────────────────────────────────────────────────────┤
│ Employee        │ MON 10    TUE 11    WED 12    THU 13    FRI 14         │
│─────────────────┼────────────────────────────────────────────────────────│
│ [x] Ricardo R.  │ Morning   Morning   Morning   [L] VL    Morning        │
│     IT Support  │ 09-18     09-18     09-18     09-18     09-18          │
│                 │                                                        │
│ [ ] Maria S.    │ +Assign   Morning   ⏱ Pending Morning   Morning        │
│     HR Asst     │           09-18     Evening   09-18     09-18          │
│                 │                                                        │
│ [x] Juan D.     │ ⚠ Conflict Evening   Evening   Evening   Evening        │
│     Sales       │           14-23     14-23     14-23     14-23          │
├──────────────────────────────────────────────────────────────────────────┤
│ 2 Employees Selected                          [Assign] [Rest Day] [Clear]│
└──────────────────────────────────────────────────────────────────────────┘
```

## 22. P0/P1/P2 Priorities
- **P0 - Required**: Redesigned Schedule Grid, Quick Assignment Popover, Interactive Filter Bar, Permission-aware Assignment vs Proposal logic, Read-only Leave/Holiday markers.
- **P1 - Strongly Recommended**: Summary Cards, Bulk Action Bar (checkboxes), Collapsible Pending Approvals Drawer, Assignment Wizard.
- **P2 - Future Enhancement**: Schedule Templates, Advanced Copy Tools (Copy Previous Week), Schedule Attention Mode.

## 23. Backend Capabilities Needed Later (Phase 3)
- `POST /api/schedule-manager/batch-assign`: Transactional endpoint taking an array of employee-date-shift combinations and returning unified success/conflict lists.
- `GET /api/schedule-manager/audit-history`: Fetch historical modifications for a cell.

## 24. Database Capabilities Needed Later (Phase 3)
- Explicit representation of "Rest Day". (Null `work_time_id` + `is_rest_day` flag).
- `schedule_audit_logs` table.

## 25. Phase 3 Implementation Inputs
- React components must be heavily modularized.
- Avoid looping API calls in the frontend; wait for batch endpoints if doing bulk actions.
- Do not build custom DatePicker elements; use MUI or existing UI library standards.
- Build the Layout and Grid first, then plug in the API contexts, then add Drawers.

## 26. Acceptance Checklist
- [x] Defined Information Hierarchy
- [x] Designed Summary Cards & Filters
- [x] Defined Grid & Cell States
- [x] Designed Quick Assign & Bulk Assignment UX
- [x] Planned Mobile Agenda View
- [x] Mapped Permission Behaviors
- [x] Drafted Wireframe
- [x] Saved to `docs/shift-schedule/phase-2-ux-dashboard-plan.md`