Use one base date, one direction, and four integer offsets. The calculator applies the year/month portion first under strict Gregorian calendar arithmetic, clamps month-end dates when the target month is shorter, then adds the week/day portion as exact day steps. The hero answer is the final date, with the weekday and net calendar-day shift shown as quick checks.
Stepwise Gregorian calendar offset:
- Parse the base date as one exact ISO calendar date.
- Convert the direction into a sign: add is positive, subtract is negative.
- Apply signed years and months first by moving to the target year/month while keeping the original day-of-month as the goal.
- If that target month does not contain the original day, clamp to the last valid day of that month. This is why
2025-01-31 + 1 month = 2025-02-28 and 2024-02-29 + 1 year = 2025-02-28.
- Convert weeks and days into an exact-day increment with exactDayDelta=7w+d and apply it after the clamp-aware year/month step.
- Derive the final weekday from the result date and derive the net day shift from the distance between the base and final UTC dates.