# payroll.holiday-entitlement

Statutory annual leave in Great Britain under the Working Time Regulations 1998
(WTR). The regulations sort workers into two groups, and so does this
function's `kind`.

## Regular workers (`regular`)

Regulations 13 and 13A: 4 weeks plus 1.6 weeks, so **5.6 weeks of the days the
worker works**, with a **maximum of 28 days**. Five days a week is exactly 28
days; six days a week would be 33.6 and is capped to 28 (`capped` is true);
2.5 days a week is 14 days.

Days a week is given in hundredths (`daysPerWeekX100`, 250 = 2.5 days) and the
answer is in hundredths of a day (`daysX100`), so part-time patterns are exact.

When employment starts or ends inside the leave year, the worker gets the
proportion of the (capped) entitlement that matches the part of the leave year
they are employed: days employed over days in the leave year, both ends
inclusive (regs 13(5) and 13A(5) for starters; reg 14 uses the same
proportion for leavers). The result is **rounded up** to the next hundredth of
a day, because an employer may round a worker's leave up but never down. The
leave year is 12 calendar months from `leaveYearStart`, so a leave year
containing 29 February has 366 days.

Employers often use GOV.UK's simpler monthly accrual for a first year (one
twelfth a month, rounded up to the next half day). That is a permitted
alternative, not the statutory proportion, and is not what this returns.

## Irregular-hours and part-year workers (`irregular-hours`, `part-year`)

For **leave years beginning on or after 1 April 2024**, regulation 15B: on the
last day of each pay period the worker accrues **12.07% of the hours worked in
that period**. A fraction of an hour under 30 minutes counts as nothing; 30
minutes or more counts as a whole hour (reg 15B(5)). 30 hours worked accrues
3.621 hours, so 4 hours, which is GOV.UK's own example. The answer is whole
hours for the pay period (`hoursAccrued`); keep the running balance yourself.

For an irregular-hours worker in a leave year that began before 1 April 2024
this refuses to answer: those years use the 5.6-week rule, averaged over a
reference period, which needs a history this function does not take.

Not modelled for accrual workers: the 28-day annual ceiling (reg 15B(4)),
which needs the employer's length of a day to convert into hours, and accrual
during sick or statutory leave (reg 15C). Both are the caller's.

The weeks, the 28-day cap, the 12.07% and the 1 April 2024 start are dated
rows in `data/holiday-rules.json`.

## Sources

- The Working Time Regulations 1998 (SI 1998/1833), regs 13, 13A, 15B and 15C
  as amended from 1 January 2024 by SI 2023/1426:
  https://www.legislation.gov.uk/uksi/1998/1833/regulation/13,
  https://www.legislation.gov.uk/uksi/1998/1833/regulation/13A,
  https://www.legislation.gov.uk/uksi/1998/1833/regulation/15B
- The Employment Rights (Amendment, Revocation and Transitional Provision)
  Regulations 2023 (SI 2023/1426): https://www.legislation.gov.uk/uksi/2023/1426/made
- GOV.UK, "Holiday entitlement: calculate leave entitlement" (12.07% of hours in
  the pay period, rounded to the nearest hour at 0.5; the 30-hour example; the
  1 April 2024 start): https://www.gov.uk/holiday-entitlement-rights/calculate-leave-entitlement