# Dashboard Drag and Drop Implementation

## Overview

This document describes the implementation of drag and drop functionality for dashboard sections, allowing users to customize the order of dashboard sections according to their preferences.

## Features

- **Drag and Drop Interface**: Users can drag dashboard sections using a drag handle to reorder them
- **Persistent Storage**: Section order is saved per user in the database
- **Reset Functionality**: Users can reset the dashboard layout to the default order
- **Visual Feedback**: Drag and drop operations provide visual feedback with CSS animations
- **Responsive Design**: Works on both desktop and mobile devices

## Implementation Details

### Database Changes

1. **Migration**: Added `dashboard_preferences` JSON column to the `users` table
   - File: `database/migrations/2025_08_19_212524_add_dashboard_preferences_to_users_table.php`
   - Stores user's dashboard preferences including section order

### User Model Updates

2. **User Model** (`app/Models/User.php`):
   - Added `dashboard_preferences` to `$fillable` array
   - Added `dashboard_preferences` to `$casts` array as JSON
   - New methods:
     - `getDefaultDashboardSectionOrder()`: Returns default section order
     - `getDashboardSectionOrder()`: Gets user's custom section order or default
     - `updateDashboardSectionOrder()`: Updates user's section order
     - `resetDashboardPreferences()`: Resets preferences to default

### Livewire Component Updates

3. **CrmDashboard Component** (`app/Livewire/CrmDashboard.php`):
   - Added `$sectionOrder` property to track current section order
   - Updated `mount()` method to load user's section order
   - New methods:
     - `updateSectionOrder()`: Handles drag and drop reordering
     - `resetSectionOrder()`: Resets section order to default
     - `getOrderedSectionsProperty()`: Returns ordered sections with metadata
   - Updated `render()` method to pass ordered sections to view

### View Template Updates

4. **Dashboard View** (`resources/views/livewire/crm-dashboard.blade.php`):
   - Added dashboard header with controls
   - Implemented sortable sections container
   - Each section includes:
     - Drag handle with grip icon
     - Section-specific header controls
     - Data attributes for JavaScript interaction
   - Integrated SortableJS library for drag and drop functionality
   - All sections now fully implemented with content from original dashboard

### Styling

5. **CSS Styles** (`resources/css/app.css`):
   - `.dashboard-section-ghost`: Styling for ghost element during drag
   - `.dashboard-section-chosen`: Styling for selected element
   - `.dashboard-section-drag`: Styling for element being dragged
   - `.drag-handle:hover`: Hover effects for drag handle

### JavaScript Integration

6. **SortableJS Integration**:
   - CDN-loaded SortableJS library
   - Configured with:
     - Handle-based dragging (`.drag-handle`)
     - Animation effects
     - CSS classes for visual feedback
   - Automatic Livewire integration for saving changes

## Dashboard Sections

The dashboard supports the following sections:

1. **Follow-up Interactions** (`follow_up_interactions`)
   - Always visible to all users
   - Shows user's pending follow-up interactions
   - Full table with interaction details, proposals, clients, and actions
   - ✅ **Fully Implemented**

2. **My Tasks** (`tasks`)
   - Always visible to all users
   - Includes filter and reset controls in section header
   - Advanced filtering: search, status, matter, category
   - Shows user's assigned tasks with full details
   - Task management actions: edit, quick edit, complete, delete
   - ✅ **Fully Implemented**

3. **My Matters** (`matters`)
   - Always visible to all users
   - Includes "View All" link in section header
   - Shows user's assigned matters with client info, status, due dates
   - Matter viewing actions
   - ✅ **Fully Implemented**

4. **Pending Proposals** (`pending_proposals`)
   - Visible only to senior lawyers, admins, and superadmins
   - Includes proposal count and debug controls in section header
   - Shows proposals pending review with amounts and creation dates
   - Proposal viewing and management actions
   - ✅ **Fully Implemented**

5. **Pending Conflicts** (`pending_conflicts`)
   - Always visible to all users
   - Title changes based on user role (admin vs regular user)
   - Shows conflict reviews requiring attention with progress indicators
   - Conflict review, conversion, and management actions
   - ✅ **Fully Implemented**

## Usage

### For Users

1. **Reordering Sections**:
   - Click and drag the grip icon (≡) next to any section title
   - Drag the section to the desired position
   - Release to save the new order automatically

2. **Resetting Layout**:
   - Click the "Reset Layout" button in the top-right corner
   - Confirms the reset and restores default section order

### For Developers

1. **Adding New Sections**:
   - Add section key to `getDefaultDashboardSectionOrder()` in User model
   - Add section definition in `getOrderedSectionsProperty()` in CrmDashboard component
   - Create section template in `resources/views/livewire/dashboard/sections/`
   - Add conditional include in main dashboard template

2. **Customizing Section Visibility**:
   - Modify the `visible` property in section definitions
   - Use user role/permission checks for conditional visibility

## Technical Requirements

- **PHP**: Laravel 12+
- **JavaScript**: SortableJS library (loaded via CDN)
- **CSS**: Tailwind CSS for styling
- **Database**: JSON column support (MySQL 5.7+, PostgreSQL 9.2+, SQLite 3.38+)

## Browser Compatibility

- Modern browsers with ES6+ support
- Touch device support for mobile drag and drop
- Fallback graceful degradation for older browsers

## Security Considerations

- User preferences are validated before saving
- Section order validation ensures only valid section keys are stored
- CSRF protection through Livewire's built-in security features
- User isolation - users can only modify their own preferences

## Performance Notes

- Section order is loaded once per page load
- Updates are performed via AJAX without full page refresh
- JSON storage is efficient for small preference objects
- Database queries are optimized with proper indexing on user_id

## Future Enhancements

Potential improvements for future versions:

1. **Section Visibility Toggle**: Allow users to hide/show sections
2. **Section Customization**: Allow users to rename section titles
3. **Import/Export**: Allow users to backup and restore dashboard layouts
4. **Role-based Defaults**: Different default layouts for different user roles
5. **Advanced Filtering**: Section-level filtering and search capabilities