# ListCompanyHolidays

## Overview

ListCompanyHolidays returns a paginated list of holiday-calendar entries, filterable by `calendarId`, date range, or year. It supports calendar browsing and admin review of registered holidays.

## Business Rules

- Results are paginated per the standard PaginationInput / buildPaginatedResult conventions
- Supports an optional `calendarId` filter that narrows results to a single [HolidayCalendar](../model/HolidayCalendar.md); omitting it returns holidays across all calendars
- Supports filtering by date range or year; omitting a filter returns the full calendar, paginated
- Returns all holiday kinds (`STATUTORY` and `PRESCRIBED`) unless a filter narrows the set
- `CompanyHoliday` is not effective-dated, so the list always reflects the current, in-place-corrected calendar — there is no historical generation to include or exclude

## Process Flow

```mermaid
flowchart TD
    A[Caller provides pagination + optional calendarId/date range/year filter] --> B[Query CompanyHoliday records matching filter]
    B --> C[Apply pagination]
    C --> D[Return paginated list of CompanyHoliday]
```

## External Dependencies

- [time-tracking::CompanyHoliday](../model/CompanyHoliday.md) model — entity being queried
- [time-tracking::HolidayCalendar](../model/HolidayCalendar.md) model — the optional `calendarId` filter narrows results to one calendar

## Error Scenarios

- **VALIDATION_ERROR**: the supplied input is malformed, out of range, or references an unrecognized enum value

## Test Cases

- returns a paginated list of CompanyHoliday records
- filtering by `calendarId` returns only holidays belonging to that calendar
- filtering by date range returns only holidays within that range
- filtering by year returns only holidays in that year
- returns an empty page when no holidays match the filter