calendaryjs-plugin-hijri 0.1.1 → 0.1.2

package/README.md

@@ -1,115 +1,70 @@
-# calendaryjs-plugin-hijri
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/npm/calendaryjs/assets/logo.svg" alt="calendaryjs" width="380" />
+</p>
 
-Islamic (Hijri) calendar plugin for [calendaryjs](https://www.npmjs.com/package/calendaryjs). Gregorian ↔ Hijri date conversion + Hijri recurring events. Uses the **tabular (civil) Islamic calendar** — arithmetic, deterministic, and round-trip safe.
+# calendaryjs-plugin-hijri
 
-> The tabular variant is computed, not observed. A sighting- or announcement-based calendar (e.g. Umm al-Qurā) may differ by ±1 day.
+> **New to calendaryjs?** Start with the [core README](https://www.npmjs.com/package/calendaryjs) — this plugin builds on its engine and builder.
 
-## Features
+Adds the **Islamic (Hijri) calendar** to calendaryjs: declare events by Hijri date, and
+convert Gregorian ↔ Hijri. Uses the **tabular (civil)** Islamic calendar — arithmetic,
+deterministic, round-trip safe.
 
-- **🌙 Hijri events** — define events by Hijri date (`type: "hijri"`)
-- **🔄 Date conversion** — Gregorian ↔ Hijri, exact inverses (round-trip safe)
-- **📅 Drift-aware** — a Hijri date can fall 0, 1, or 2 times in a Gregorian year; all occurrences are returned
-- **🗓 Leap years** — standard 30-year tabular cycle (11 leap years)
+> The tabular variant is computed, not observed; a sighting-based calendar (e.g. Umm
+> al-Qurā) may differ by ±1 day.
 
-## Installation
+## Install
 
 ```bash
-pnpm add calendaryjs calendaryjs-plugin-hijri
+npm i calendaryjs calendaryjs-plugin-hijri
 ```
 
-## Requirements
+## Use it
 
-- `calendaryjs` >= 0.1.0
+Register the plugin, then declare Hijri events with the `hijri.date()` selector — the
+engine resolves them to Gregorian (a Hijri date can fall 0, 1 or 2 times in a Gregorian
+year; all occurrences are returned):
 
-## Quick Start
-
-```typescript
+```ts
 import { calendary } from "calendaryjs";
+import { every } from "calendaryjs/builder";
 import { hijri } from "calendaryjs-plugin-hijri";
 
-const cal = calendary();
-cal.use(hijri());
+const cal = calendary().use(hijri());
 
 cal.addGroup({
   id: "islamic-holidays",
-  name: "Islamic Holidays",
   events: [
-    {
-      type: "hijri",
-      id: "islamic-new-year",
-      hijriMonth: 1,
-      hijriDay: 1,
-      title: "Islamic New Year",
-    },
-    { type: "hijri", id: "eid-al-fitr", hijriMonth: 10, hijriDay: 1, title: "Eid al-Fitr" },
-    { type: "hijri", id: "eid-al-adha", hijriMonth: 12, hijriDay: 10, title: "Eid al-Adha" },
+    every("year").on(hijri.date(1, 1)).title("Islamic New Year"),
+    every("year").on(hijri.date(10, 1)).title("Eid al-Fitr"),
+    every("year").on(hijri.date(12, 10)).title("Eid al-Adha"),
   ],
 });
 
-// Resolves Hijri dates to Gregorian automatically
-const events = cal.getEventsInRange("2025-01-01", "2025-12-31");
+cal.getEventsInRange("2025-01-01", "2025-12-31"); // → Gregorian dates
 ```
 
-## Event Type
-
-### `hijri`
+Prefer raw config? The selector compiles to a plain `hijri` event:
 
-Events based on Hijri calendar dates.
-
-```typescript
-{
-  type: 'hijri';
-  id: string;
-  hijriMonth: number;  // 1-12
-  hijriDay: number;    // 1-30
-  title?: string;
-  // ... other standard event properties
-}
+```ts
+{ type: "hijri", id: "eid", hijriMonth: 10, hijriDay: 1, title: "Eid al-Fitr" }
 ```
 
-Because a Hijri month/day drifts ~11 days earlier each Gregorian year, an event
-may occur **twice** (early January + late December) or **not at all** within a
-given Gregorian year. The engine returns every occurrence that lands in range.
-
-## Date Conversion
+## Convert dates
 
-```typescript
+```ts
 import { gregorianToHijri, hijriToGregorian } from "calendaryjs-plugin-hijri";
 
-// Gregorian → Hijri
-gregorianToHijri({ year: 2024, month: 7, day: 8 });
-// → { year: 1446, month: 1, day: 1 }
-
-// Hijri → Gregorian
-hijriToGregorian({ year: 1446, month: 1, day: 1 });
-// → { year: 2024, month: 7, day: 8 }
+gregorianToHijri({ year: 2025, month: 1, day: 1 }); // → { year, month, day }
+hijriToGregorian({ year: 1446, month: 1, day: 1 }); // → { year, month, day }
 ```
 
-### Calendar helpers
-
-```typescript
-import { isHijriLeapYear, hijriMonthLength, isValidHijriDate } from "calendaryjs-plugin-hijri";
-
-isHijriLeapYear(1447); // → true  (355-day year)
-hijriMonthLength(1446, 1); // → 30 (odd months are 30 days)
-isValidHijriDate({ year: 1446, month: 12, day: 30 }); // → false (not a leap year)
-```
-
-## Optional: enrich days with Hijri info
-
-```typescript
-const cal = calendary().use(hijri({ enrichDays: true }));
-cal.addGroup({ id: "g", events: [] });
-
-const [day] = cal.getDays({ from: "2024-07-08", to: "2024-07-08" });
-day.hijri; // → { year: 1446, month: 1, day: 1 }
-```
+## Reference
 
-## Related Packages
+**Event type `hijri`** — `hijriMonth` (1–12) · `hijriDay` (1–30), plus every standard
+[event property](https://www.npmjs.com/package/calendaryjs#event-properties).
 
-- [calendaryjs](https://www.npmjs.com/package/calendaryjs) - Core package
-- [calendaryjs-plugin-lunar](https://www.npmjs.com/package/calendaryjs-plugin-lunar) - Lunisolar calendar
-- [calendaryjs-plugin-liturgical](https://www.npmjs.com/package/calendaryjs-plugin-liturgical) - Liturgical calendar
+**Exports** — `hijri()` · `hijri.date(month, day)` · `gregorianToHijri` · `hijriToGregorian` · `isValidHijriDate` · `isHijriLeapYear` · `hijriMonthLength`.
 
 ## License
 

package/dist/index.cjs

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "calendaryjs-plugin-hijri",
-  version: "0.1.1"};
+  version: "0.1.2"};
 
 // src/converter.ts
 var ISLAMIC_EPOCH = 1948440;

package/dist/index.js

@@ -1,7 +1,7 @@
 // package.json
 var package_default = {
   name: "calendaryjs-plugin-hijri",
-  version: "0.1.1"};
+  version: "0.1.2"};
 
 // src/converter.ts
 var ISLAMIC_EPOCH = 1948440;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "calendaryjs-plugin-hijri",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Islamic (Hijri) calendar plugin for calendaryjs — Gregorian ↔ Hijri date conversion (tabular/civil) and Hijri recurring events.",
   "type": "module",
   "sideEffects": false,
@@ -39,7 +39,7 @@
     "moment-hijri": "^3.0.0",
     "typescript": "^5.3.2",
     "vitest": "^4.0.18",
-    "calendaryjs": "0.2.1"
+    "calendaryjs": "0.2.2"
   },
   "files": [
     "dist"