# User Module Usage Instructions

## Overview
The `feat/user` branch introduces comprehensive user authentication, dashboard access, and profile management capabilities. It adheres strictly to the repository-service-controller pattern established in the base branch, incorporating advanced AJAX-based form submissions and real-time frontend validation for a dynamic, smooth user experience.

---

## Setup Briefing

When pulling or checking out this branch, follow these steps to ensure all dependencies and configurations are loaded correctly:

1. **Install Dependencies**: The branch introduces `proengsoft/laravel-jsvalidation` for real-time frontend validation.
   ```bash
   composer install
   npm install
   ```

2. **Publish Vendor Assets**: Ensure the JS validation scripts are available in the public directory.
   ```bash
   php artisan vendor:publish --provider="Proengsoft\JsValidation\JsValidationServiceProvider" --tag=public --force
   ```

3. **Run Migrations**: Apply any new schema changes (if applicable).
   ```bash
   php artisan migrate
   ```

4. **Rebuild Assets**: Rebuild the Vite assets to compile the newly added validation scripts.
   ```bash
   npm run build
   ```

---

## Functionality Details

### 1. User Authentication (AJAX-Enabled)
All authentication forms operate via AJAX to prevent full-page reloads. Errors are returned via JSON and automatically mapped to their respective input fields, or displayed globally using the built-in toaster notifications.

- **Login (`/login`)**:
  - **Controller**: `LoginController@login` processes the credentials.
  - **Function**: Uses Laravel's built-in `Auth::attempt`. On success, it returns a JSON response specifying the redirect URL (`/dashboard`). On failure, it returns a 422 JSON response with validation errors.
  
- **Registration (`/register`)**:
  - **Controller**: `RegisterController@register` (or `ResgisterController`).
  - **Function**: Validates input using `RegisterRequest` and creates a new `User` record. Upon creation, it logs the user in and triggers an AJAX redirect to the dashboard.
  - **Validation**: Enforces password strength rules and unique email constraints.

- **Password Recovery (`/forgot-password` & `/reset-password`)**:
  - **Controller**: `ForgotPasswordController`.
  - **Function**: Handles sending the password reset link to the registered email and processing the final password reset token. 
  - **Workflow**: Submitting the forgot password form sends an asynchronous request and displays a success toast. The reset form securely verifies the token and updates the user's password.

### 2. User Dashboard
- **Route**: `/dashboard`
- **Controller**: `DashboardController@index`.
- **Function**: Serves as the landing hub for authenticated users. It returns the `user.dashboard.index` view, utilizing the `user-header` and `page-container` components for a consistent layout.

### 3. User Profile Management
The profile management is handled by the `ProfileController` and strictly delegates business logic to the `UserProfileService`.

- **View Profile**: 
  - Retrieves the currently authenticated user's data and renders the `user.profile.index` blade view.
- **Update Profile Information**:
  - **Request**: `UpdateProfileRequest` ensures the name and email are valid.
  - **Service**: `UserProfileService@updateProfile` saves the changes.
  - **Response**: Triggers a success toaster notification upon successful update via AJAX.
- **Change Password**:
  - **Request**: `ChangePasswordRequest` validates that the `current_password` matches the database, and that `password` and `password_confirmation` align.
  - **Service**: `UserProfileService@changePassword` securely hashes and updates the new password.

---

## JavaScript & Validation Architecture

This branch implements a robust JavaScript architecture for handling forms:

1. **Laravel JSValidation (`public/vendor/jsvalidation`)**:
   - The forms use the `{!! JsValidator::formRequest(...) !!}` facade to automatically translate Laravel PHP FormRequests into frontend JavaScript validation rules.
   
2. **AJAX Form Handlers (`resources/js/common/validation.js`)**:
   - Instead of standard HTML submissions, forms are hijacked via JavaScript.
   - Using `axios`, the payload is sent to the corresponding Controller route.
   - **Success**: The script looks for a `redirect` URL in the JSON response and automatically forwards the user.
   - **Error**: Validation errors returned as 422 HTTP status codes are parsed, and error messages are injected dynamically under the respective input fields using standard styling.

---

## Core File Paths & Structure

- **Controllers**:
  - `app/Http/Controllers/User/Auth/LoginController.php`
  - `app/Http/Controllers/User/Auth/RegisterController.php`
  - `app/Http/Controllers/User/Auth/ForgotPasswordController.php`
  - `app/Http/Controllers/User/Dashboard/DashboardController.php`
  - `app/Http/Controllers/User/Profile/ProfileController.php`

- **Form Requests**:
  - `app/Http/Requests/RegisterRequest.php`
  - `app/Http/Requests/ForgotPasswordRequest.php`
  - `app/Http/Requests/User/Profile/UpdateProfileRequest.php`
  - `app/Http/Requests/User/Profile/ChangePasswordRequest.php`

- **Services**:
  - `app/Services/User/UserProfileService.php`

- **Views (`resources/views/pages/user/`)**:
  - `auth/login.blade.php`
  - `auth/register.blade.php`
  - `auth/forgot-password.blade.php`
  - `auth/reset-password.blade.php`
  - `dashboard/index.blade.php`
  - `profile/index.blade.php`

- **Routing**:
  - `routes/user.php` (contains all `auth` middleware group routes for users).

---

## Changes Made When Merged with Base

1. **UI Alignment**: The authentication and profile views were fully refactored to utilize the base branch's Blade components (e.g., `<x-forms.input>`, `<x-buttons.primary>`). This ensures UI consistency across the entire application.
2. **Layout Integration**: Implemented `<x-layouts.user-header>` and `<x-layouts.user.page-container>` wrappers to inherit the standardized base styling.
3. **Toast Notifications**: Replaced custom alert banners with the base branch's global Alpine.js toaster component for a streamlined notification experience.