Calendrical version 0.4.0

[0.4.0] — 2026-05-17

Bug Fixes

• Calendrical.LunarJapanese.new/3, Calendrical.Chinese.new/3, and Calendrical.Korean.new/3 rejected valid {m, :leap} inputs in the documented traditional notation — the validator compared the user's traditional month number against the ordinal position returned by leap_month/1, which is always off by one. The check now correctly converts ordinal to traditional before comparing, the private helper has been renamed valid_traditional_date?/5 to disambiguate from the 3-arity valid_date?/3 callback used by Date.new/4, and the public Date.new/4 ordinal contract is unchanged.

• Test support module renamed from Calendrical.Date to Calendrical.Test.DateGenerator to free the Calendrical.Date namespace for the new parser module. Affects test/property_test.exs and test/day_of_week_test.exs only — no public API impact.

Added

• traditional_leap_month/1 on each of the three lunisolar calendars (Calendrical.LunarJapanese, Calendrical.Chinese, Calendrical.Korean), returning the traditional (1..12) number of the intercalary month — the number the leap month repeats — as a companion to leap_month/1 which returns the ordinal position (1..13).

• Calendrical.Time.parse/2 and Calendrical.DateTime.parse/2 — locale-aware time and date-time parsers completing the parser trio alongside Calendrical.Date.parse/2, TR35-compliant for hour-cycle resolution, day-period names, fractional seconds, and CLDR glue patterns. See the moduledocs for the day-period inheritance and datetime-glue backtracking strategy.

• Calendrical.TimeParseError and Calendrical.DateTimeParseError — structured errors carrying :input and :locale.

• Calendrical.Date.parse/2 — locale-aware parser for user-typed date strings across every Calendar-behaviour module exposing cldr_calendar_type/0 (Gregorian, Buddhist, Japanese imperial, Islamic, Persian, Hebrew, ROC, Coptic, Ethiopic, Indian, …). Handles CLDR lenient-scope-date separator equivalences, non-Latin digit transliteration, 2-digit year pivoting, and era markers — see Calendrical.Date.Parser for the full strategy.

• Calendrical.Date.parse_range/2 — locale-aware range parser. Accepts either a single string (split on CLDR's intervalFormatFallback separator) or a {from, to} tuple, with CLDR interval-skeleton inheritance so "May 5 – May 10, 2026" parses even though the left endpoint has no year.

• Calendrical.DateParseError and Calendrical.DateRangeParseError — structured errors carrying :input, :locale, :calendar, plus :reason and :cause for ranges.

Documentation

• Each lunisolar calendar's moduledoc now has a "Two month numbering conventions" section explaining the difference between ordinal months (used by Date.t, Date.new/4, Date.convert/2, and the Calendar callbacks) and traditional months (used by new/3 and the return value of lunar_month_of_year/1). The previous undocumented dichotomy could silently produce dates one full lunar month off after the intercalary in leap years.

• The new/3 and new!/3 docstrings on each lunisolar calendar now state explicitly that the lunar_month argument is traditional (1..12 with {m, :leap} for the intercalary), with examples showing how the traditional number maps to the ordinal stored on the resulting Date.t struct.