calendaryjs-plugin-liturgical 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 calendaryjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# calendaryjs-plugin-liturgical
+
+Liturgical calendar plugin for [Calendary](https://github.com/calendaryjs/calendaryjs). Adds support for Easter calculation and offset-based events.
+
+## Features
+
+- **✝️ Easter Calculation** - Computus algorithm for accurate Easter dates
+- **📅 Offset Events** - Events relative to Easter or other base events
+- **⛪ Church Calendar** - Full liturgical year support
+- **🔧 Flexible** - Works with any Christian denomination
+
+## Installation
+
+```bash
+pnpm add calendaryjs calendaryjs-plugin-liturgical
+```
+
+## Requirements
+
+- `calendaryjs` >= 0.1.0
+
+## Quick Start
+
+```typescript
+import { calendary } from "calendaryjs";
+import { liturgical } from "calendaryjs-plugin-liturgical";
+
+const cal = calendary();
+cal.use(liturgical());
+
+cal.addGroup({
+  id: "church",
+  name: "Church Calendar",
+  events: [
+    { type: "easter", id: "easter", title: "Easter Sunday" },
+    { type: "offset", id: "ash-wed", baseEvent: "easter", offsetDays: -46, title: "Ash Wednesday" },
+    {
+      type: "offset",
+      id: "palm-sunday",
+      baseEvent: "easter",
+      offsetDays: -7,
+      title: "Palm Sunday",
+    },
+    {
+      type: "offset",
+      id: "good-friday",
+      baseEvent: "easter",
+      offsetDays: -2,
+      title: "Good Friday",
+    },
+    { type: "offset", id: "pentecost", baseEvent: "easter", offsetDays: 49, title: "Pentecost" },
+  ],
+});
+
+const events = cal.getEventsInRange("2025-01-01", "2025-12-31");
+```
+
+## Event Types
+
+### `easter`
+
+Easter Sunday, calculated using the Computus algorithm.
+
+```typescript
+{
+  type: 'easter';
+  id: string;
+  title?: string;
+  // ... other standard event properties
+}
+```
+
+### `offset`
+
+Events offset from a base event (typically Easter).
+
+```typescript
+{
+  type: 'offset';
+  id: string;
+  baseEvent: string;    // ID of the base event
+  offsetDays: number;   // Days offset (negative = before, positive = after)
+  title?: string;
+  // ... other standard event properties
+}
+```
+
+## Common Liturgical Offsets
+
+| Event          | Offset from Easter |
+| -------------- | ------------------ |
+| Ash Wednesday  | -46                |
+| Palm Sunday    | -7                 |
+| Holy Thursday  | -3                 |
+| Good Friday    | -2                 |
+| Holy Saturday  | -1                 |
+| Easter Monday  | +1                 |
+| Ascension      | +39                |
+| Pentecost      | +49                |
+| Trinity Sunday | +56                |
+| Corpus Christi | +60                |
+
+## Example: Full Liturgical Year
+
+```typescript
+import { calendary } from "calendaryjs";
+import { liturgical } from "calendaryjs-plugin-liturgical";
+
+const cal = calendary();
+cal.use(liturgical());
+
+cal.addGroup({
+  id: "liturgical",
+  name: "Liturgical Calendar",
+  events: [
+    // Easter
+    { type: "easter", id: "easter", title: "Easter Sunday" },
+
+    // Lent
+    { type: "offset", id: "ash-wed", baseEvent: "easter", offsetDays: -46, title: "Ash Wednesday" },
+
+    // Holy Week
+    {
+      type: "offset",
+      id: "palm-sunday",
+      baseEvent: "easter",
+      offsetDays: -7,
+      title: "Palm Sunday",
+    },
+    {
+      type: "offset",
+      id: "holy-thursday",
+      baseEvent: "easter",
+      offsetDays: -3,
+      title: "Holy Thursday",
+    },
+    {
+      type: "offset",
+      id: "good-friday",
+      baseEvent: "easter",
+      offsetDays: -2,
+      title: "Good Friday",
+    },
+    {
+      type: "offset",
+      id: "holy-saturday",
+      baseEvent: "easter",
+      offsetDays: -1,
+      title: "Holy Saturday",
+    },
+
+    // Easter Season
+    {
+      type: "offset",
+      id: "easter-monday",
+      baseEvent: "easter",
+      offsetDays: 1,
+      title: "Easter Monday",
+    },
+    {
+      type: "offset",
+      id: "divine-mercy",
+      baseEvent: "easter",
+      offsetDays: 7,
+      title: "Divine Mercy Sunday",
+    },
+    { type: "offset", id: "ascension", baseEvent: "easter", offsetDays: 39, title: "Ascension" },
+    { type: "offset", id: "pentecost", baseEvent: "easter", offsetDays: 49, title: "Pentecost" },
+
+    // Ordinary Time
+    { type: "offset", id: "trinity", baseEvent: "easter", offsetDays: 56, title: "Trinity Sunday" },
+    {
+      type: "offset",
+      id: "corpus-christi",
+      baseEvent: "easter",
+      offsetDays: 60,
+      title: "Corpus Christi",
+    },
+  ],
+});
+```
+
+## Easter Calculation
+
+The plugin uses the Computus algorithm to calculate Easter dates:
+
+```typescript
+import { computeEaster } from "calendaryjs-plugin-liturgical";
+
+const easter2025 = computeEaster(2025);
+// Returns: Date object for Easter Sunday 2025
+```
+
+## Related Packages
+
+- [calendaryjs](https://github.com/calendaryjs/calendaryjs/tree/main/packages/calendaryjs) - Core package
+- [calendaryjs-plugin-lunar](https://github.com/calendaryjs/calendaryjs/tree/main/packages/lunar) - Lunar calendar
+
+## License
+
+MIT