feat: Add liturgical calendar module

[marcodelpin]

Summary

Add comprehensive TypeScript liturgical calendar module (v1.1.0) - a client-side complement to the existing liturgical-calendar-api (PHP server).

Relationship to liturgical-calendar-api

Aspect	liturgical-calendar-api	This Module
Language	PHP	TypeScript
Runtime	Server-side API	Browser + Node.js
Purpose	REST API endpoints	Library/SDK
Output	JSON/XML/ICS	CLEDR IDs + fragments

This TypeScript module enables:

• Offline calendar computation in browsers
• Node.js applications without PHP dependency
• React/Vue/Angular liturgical apps
• CLEDR ID generation for content lookup

Features

Core Calendar

• Computus: Easter calculation (Meeus/Jones/Butcher, 1583-2499)
• Precedence: Full UNLY 14-level Table of Liturgical Days
• Temporale: All moveable feasts derived from Easter
• Sanctorale: Fixed feast calendar with precedence rules
• Fragments: Path generation for liturgical content lookup
• Latin enums: International compatibility

Liturgical Support

• LitColor: Liturgical colors (green, purple, white, red, rose) with i18n
• LitCommon: Common texts (Martyrs, Pastors, Virgins, etc.) with Latin translations

Configuration (NEW)

• Roman Missal editions: 1970, 2002, 2008
• Moveable feast transfers:
  • Ascension: Thursday vs Sunday
  • Corpus Christi: Thursday vs Sunday
  • Epiphany: January 6 vs Sunday
• National calendars: 14 countries (VA, IT, US, GB, DE, FR, ES, PL, BR, PH, IE, AU, CA, MX, AR)
• Diocese support: Custom configuration with patron saints, dedication dates

Internationalization (NEW)

• 8 locales: Latin, Italian, English, Spanish, French, German, Portuguese, Polish
• Full translations: Seasons, ranks, colors, days, Mass parts, Liturgy of Hours
• Helper functions: getSeasonName(), formatWeekName(), getTerm()

Planned Enhancements

• National calendar proper celebrations (saints, feasts)
• Additional locales (more languages)
• Martyrology integration

Test Coverage

491 tests passing, 2087 expect() calls (was 375/1610)

External Validation Sources

• Church Calendar API (calapi.inadiutorium.cz)
• CEI (chiesacattolica.it) - Italian Bishops
• USCCB - US Bishops official calendars

Rare Exceptions Tested

• Kyriopascha 2035 (Easter on March 25)
• St. Joseph on Palm Sunday (2062)
• Annunciation transfers during Holy Week
• Immaculate Conception on Advent Sunday

Credits

Original code: ePrex Calendar System by Marco Del Pin

[JohnRDOrazio]

Thank you for your effort @marcodelpin, however the purpose of the current repository isn't to host an application, but simply to establish the canonicalized IDs that can be a reference for anyone building a liturgical calendar application. A reference for this repository is the Unicode Consortium "Common Locale Data Repository" (see https://github.com/unicode-org/cldr). In any case the temporale.ts and sanctorale.ts files were useful for the mapping process which I continued in this initial external repository: https://github.com/JohnRDOrazio/liturgical-calendar-ids.

After mapping the IDs from your temporale.ts and sanctorale.ts to the litcal IDs, it would seem that there are a number of IDs that are still missing on the ePrex side (unless they are to be found elsewhere?), see:

1. https://github.com/JohnRDOrazio/liturgical-calendar-ids/blob/main/eprex/sanctorale_missing_keys.md
2. https://github.com/JohnRDOrazio/liturgical-calendar-ids/blob/main/eprex/temporale_missing_keys.md

I have documented some special mappings between ePrex and LitCal IDs in README - Special mappings between eprex and litcal.

I will now attempt to look over the romcal codebase to see if I can extract and map the IDs from there too.

Once we have a comprehensive mapping of all the IDs, I will publish the JSON / MD files here; again, no application level calculations in this repository, just the process of canonicalization of the IDs.

[marcodelpin]

@JohnRDOrazio Thank you for the detailed feedback and for creating the liturgical-calendar-ids repo!

I now understand the CLEDR philosophy (modeled after Unicode CLDR) - it should be a pure data repository, not code.

My Proposal:

1. Close this PR as-is (calendar module is not appropriate for CLEDR)

2. New contribution to CLEDR - I'll submit a smaller PR with ONLY:

   • Mapping files to complete eprex_key entries in sanctorale/temporale JSON
   • Additional ID entries for the 48 temporale keys you identified
   • This will help complete the canonicalization effort

3. Validation code → separate repository
   The TypeScript calendar (491 tests, edge cases validation) will go to a new repo:

   • Either CatholicOS/liturgical-calendar-ts
   • Or as a module within CatholicOS/liturgical-calendar-mcp

   This code serves as a reference implementation and validation tool for the CLEDR IDs - it can computationally verify that the canonical IDs are correct for any date.

Benefits:

• CLEDR stays pure data ✅
• The test suite validates CLEDR correctness ✅
• Other implementations (romcal, litcal, etc.) can use CLEDR IDs as source of truth ✅

Let me know if you'd prefer the code in liturgical-calendar-mcp or a new dedicated repo.

[marcodelpin]

Closing this PR — after @JohnRDOrazio's feedback, it's clear CLEDR should remain a pure data registry (canonicalized IDs), not host application code. If I contribute in the future, it will be aligned with that scope. Thanks for the guidance!