Birthdays Report

1. What does this feature do? (High-Level Overview)

This feature provides a Birthdays reporting table where users can review birthday records for clients and employees. It supports server-side filtering, sorting, and pagination, helping teams quickly identify upcoming, past, or all birthdays by month and entity type.

2. Who is this for? (Roles & Permissions)

• Users who can access Reports and meet the Birthdays Report card requirements in Reports Access.
• In Reports Access, the Birthdays Report card is configured with both permissions: view_all_clients and view_employees.
• Users with those permissions can navigate to /reports/birthdays from the report card.
• Inside this component, row links are permission-aware:
• Client names link to profile only if view_all_clients is available.
• Employee names link to profile only if view_employees is available.
• Without those permissions, names are displayed as plain text.

Required permissions used by this feature path:

• view_all_clients: required by Reports Access card visibility and client profile link behavior.
• view_employees: required by Reports Access card visibility and employee profile link behavior.

3. Business Rules & Enforcements

• Rule 1: The report loads data automatically when the page opens.
• Rule 2: The report starts with these defaults:
  • Period: Upcoming
  • Type: All
  • Month: Not selected
  • Page: 1
  • Rows per page: 100
  • Sort: Days Left (ascending)
• Rule 3: Search text is cleaned before sending (extra spaces removed, converted to lowercase).
• Rule 4: Search and filter changes are applied after a short pause (about 300ms) to avoid constant reloading.
• Rule 5: When any filter changes, results go back to page 1.
• Rule 6: Reset returns everything to the original defaults and reloads data.
• Rule 7: Sorting is handled by the server. If no sort is selected, it uses Days Left (ascending).
• Rule 8: Pagination is handled by the server using current page and rows per page.
• Rule 9: Pagination stays compact:
  • If total pages are 5 or fewer, show all page numbers.
  • If total pages are more than 5, show the current page plus one page before and after.
• Rule 10: If a current location exists, it is included in the request.
• Rule 11: While loading, the table shows skeleton rows.
• Rule 12: If no data is found, show: Data not available.
• Rule 13: If loading fails, show: Unable to load birthdays report. Please try again., and clear table/pagination data.
• Rule 14: If Period is Upcoming and the selected month is already past, show an informational message because results may be empty.

4. UI Placement

• Reports entry path:

1. Main app -> Reports.
2. Reports Access -> Human Resources -> Birthdays Report card.
3. Navigates to primary route: /reports/birthdays.

• Main screen sections in this feature:

1. Back button (returns browser history).
2. Search input (by name text).
3. Type filter (All, Clients, Employees).
4. Period filter (Upcoming, Past, All).
5. Month filter (January to December).
6. Reset button (restores default state).
7. Informational alert for Upcoming + past month combinations.
8. Error alert when API load fails.
9. Birthdays table (sortable columns: Full Name, Birth Date, Days Left).
10. Footer controls (record range and pagination with Previous/Next and page buttons).

5. How-To Guide (Step-by-Step)

Scenario A: Review upcoming birthdays

1. Open Reports and enter Birthdays Report.
2. Keep Period as Upcoming (default) or adjust as needed.
3. Optionally type a name in Search.
4. Optionally choose Type (All, Clients, Employees).
5. Optionally choose a Month.
6. Review matching rows with Full Name, Birth Date, and Days Left.

Scenario B: Narrow results to employees or clients

1. Use Type filter to select Clients or Employees.
2. Optionally add Search text and Month.
3. Use sorting on Full Name, Birth Date, or Days Left.
4. Navigate through pages with Previous/Next or direct page buttons.

Scenario C: Reset and start over

1. Click Reset.
2. Confirm filters return to defaults (Upcoming, All, no month).
3. Confirm pagination and sorting also return to defaults.
4. Continue filtering from a clean state.

6. What happens if…? (Edge Cases / FAQ)

• Q: What happens if no filters are changed?

• A: The component loads immediately using defaults (upcoming period, all entity types, page 1, per_page 100, sorted by days_until_birthday asc).

• Q: What if the user types spaces or mixed-case text in Search?

• A: Input is normalized to trimmed lowercase before being sent to API.

• Q: What if the user changes filters rapidly?

• A: Requests are debounced by 300ms, so rapid changes coalesce into a single load.

• Q: What if Upcoming period is selected with a month already in the past?

• A: An info alert is displayed warning that results can be empty.

• Q: What if API returns no data?

• A: The table displays Data not available.

• Q: What if API fails while loading?

• A: Loading stops, an error alert is shown, and rows/pagination are cleared.

• Q: What if user lacks permission for profile navigation links?

• A: Names are shown as plain text instead of clickable links.

• Q: What if backend response shape changes?

• A: The component attempts normalization from supported shapes (array, data array, or object values containing row entities).