HRM-System/docs/PLAN-employee-form-errors.md

PLAN - Employee Form Error Handling

1. Context & Objective

The user wants to improve the error handling experience when creating or editing an Employee. Currently, when validation fails, a generic "Please correct the errors in the form" toast is displayed, and the user has to manually scroll to find the red fields.

The objective is to:

1. Display a more descriptive error toast (e.g. specifying which field is missing).
2. Automatically scroll the page to the section/field containing the error so the user can immediately fill it out.

2. Target Files

• resources/js/pages/hr/employees/create.tsx
• resources/js/pages/hr/employees/edit.tsx

3. Task Breakdown

Phase 1: Update Error Toast Message

• In the onError callback of router.post() / router.put(), retrieve the first validation error from the errors object.
• Change toast.error(t('Please correct the errors in the form')); to display the specific error, e.g. toast.error(Object.values(errors)[0] || t('Please correct the errors in the form'));.

Phase 2: Implement Auto-Scroll to Error

• Add a mechanism inside onError (possibly wrapped in setTimeout to ensure DOM updates) to locate the first error element.
• Since the fields with errors have a specific class (like border-red-500 or the error text paragraph has text-red-500), use document.querySelector('.text-red-500') or similar.
• Call .scrollIntoView({ behavior: 'smooth', block: 'center' }) on the found element.
• Optionally call .focus() on the associated input if applicable.

4. Verification Checklist

• Submit an empty employee creation form.
• Verify the toast displays a specific error message (e.g. "Full Name is required").
• Verify the page smoothly scrolls to the top where the "Full Name" field is.
• Submit an empty employee edit form and verify the same behavior.