@coreify/tarikh 1.0.0 → 1.0.2

package/README.md

@@ -1,478 +1,557 @@
-# @coreify/tarikh
-
-The Bangladeshi date toolkit for modern apps.
-
-Format dates, render Bangla calendar, and handle localization correctly.
+# @coreify/tarikh
+
+[![npm version](https://img.shields.io/npm/v/@coreify/tarikh)](https://www.npmjs.com/package/@coreify/tarikh)
+[![downloads](https://img.shields.io/npm/dm/@coreify/tarikh)](https://www.npmjs.com/package/@coreify/tarikh)
+[![license](https://img.shields.io/npm/l/@coreify/tarikh)](https://github.com/coreify/tarikh/blob/main/package/LICENSE)
+
+> The first JavaScript date library with Bangla and Hijri calendar support.
+> Built for Bangla dates, Bengali calendar conversion, and culturally correct formatting.
+
+| Main export | What it does |
+| ----------- | ------------ |
+| `format()` | Standard, Bangla, Hijri, and hybrid date formatting |
+| `toBanglaCalendar()` | Convert Gregorian dates into the Bangla calendar |
+| `toHijriCalendar()` | Convert Gregorian dates into the Hijri calendar |
+| `fromNow()` | Render relative time like today, yesterday, and tomorrow |
+| `HIJRI_TIME_ZONES` | Canonical supported Hijri time zones |
+
+## At a Glance
+
+| Snapshot | Example |
+| -------- | ------- |
+| Bangla spoken format | `format("2026-04-14", { mode: "bangla", locale: "bn-BD", format: "spoken" })` |
+| Rendered output | `পহেলা বৈশাখ ১৪৩৩ বঙ্গাব্দ` |
 
+```ts
+format("2026-04-14", {
+  mode: "bangla",
+  locale: "bn-BD",
+  format: "spoken"
+});
+// → "পহেলা বৈশাখ ১৪৩৩ বঙ্গাব্দ"
+```
+
+## Demo
+
+| Demo | Link |
+| ---- | ---- |
+| Live demo | [tarikh.js.org](https://tarikh.js.org) |
+
 ## Why this exists
 
-JavaScript's `Intl.DateTimeFormat` and libraries like Day.js / date-fns don't solve these problems:
-
-- **Bangla calendar** — Convert Gregorian dates to Bengali calendar (বৈশাখ, চৈত্র, etc.)
-- **Bangla digits** — Render `৩১ মার্চ ২০২৬` instead of `31 March 2026`
-- **Hybrid formatting** — Mix English and Bangla in a single date string
-- **Weekday and time formatting** — Render weekday, hour, minute, and second output
-- **Natural relative time** — Use `yesterday`, `tomorrow`, `গতকাল`, `আগামীকাল`, etc.
-- **Cultural correctness** — Bangladeshi locale-aware formatting out of the box
-
-`@coreify/tarikh` is a zero-dependency, tree-shakeable, SSR-safe toolkit purpose-built for Bangladesh.
-
-## Installation
-
-```bash
-npm install @coreify/tarikh
-```
-
-## Quick Start
-
-```ts
+| Why this exists | Summary |
+| --------------- | ------- |
+| Bangla calendar | Convert Gregorian dates to Bengali calendar values like বৈশাখ and চৈত্র |
+| Hijri calendar | Render Islamic calendar dates alongside Bangla and Gregorian output |
+| Bangla digits | Render `৩১শে মার্চ ২০২৬ খ্রিস্টাব্দ` instead of `31st March 2026` |
+| Hybrid formatting | Mix English and Bangla in a single date string |
+| Weekday/time | Render weekday, hour, minute, and second output |
+| Relative time | Use `yesterday`, `tomorrow`, `গতকাল`, `আগামীকাল`, etc. |
+| Cultural correctness | Bangladeshi locale-aware formatting out of the box |
+
+> `@coreify/tarikh` is a zero-dependency, tree-shakeable, SSR-safe toolkit purpose-built for Bangladesh.
+
+## Installation
+
+```bash
+npm install @coreify/tarikh
+```
+
+## Quick Start
+
+```ts
 import {
-  formatDate,
-  formatBanglaCalendar,
+  HIJRI_TIME_ZONES,
+  format,
   fromNow,
-  toBanglaCalendar
+  toBanglaCalendar,
+  toHijriCalendar
 } from "@coreify/tarikh";
 
-formatDate(new Date(), { locale: "bn-BD" });
-// → "৩১ মার্চ ২০২৬"
-
-// Structured Bangla calendar conversion
-// `monthIndex` stays numeric; `bn-BD` localizes `day`, `month`, and `year`.
-toBanglaCalendar("2026-03-31");
-// → { day: 17, month: "Chaitra", monthIndex: 12, year: 1432 }
-
-toBanglaCalendar("2026-03-31", { locale: "bn-BD" });
-// → { day: "১৭", month: "চৈত্র", monthIndex: 12, year: "১৪৩২" }
-
-formatBanglaCalendar("2026-03-31");
-// → "17 Chaitra 1432"
-
-formatBanglaCalendar("2026-03-31", { locale: "bn-BD" });
-// → "১৭ই চৈত্র ১৪৩২"
-
-formatBanglaCalendar("2026-04-14", { locale: "bn-BD" });
+const [defaultHijriZone, utcHijriZone] = HIJRI_TIME_ZONES;
+
+// Preferred entry points:
+format("2026-03-31", { mode: "standard" });
+format("2026-03-31", { mode: "bangla" });
+format("2026-03-31", { mode: "hijri" });
+format("2026-03-31", { mode: "hybrid" });
+
+// Token-based output still works.
+format("2026-03-31", { pattern: "DD MMM YYYY" });
+// → "31 Mar 2026"
+
+// Structured Bangla calendar conversion
+// `monthIndex` stays numeric; `bn-BD` localizes `day`, `month`, and `year`.
+toBanglaCalendar("2026-03-31");
+// → { day: 17, month: "Chaitra", monthIndex: 12, year: 1432 }
+
+toBanglaCalendar("2026-03-31", { locale: "bn-BD" });
+// → { day: "১৭", month: "চৈত্র", monthIndex: 12, year: "১৪৩২" }
+
+format("2026-03-31", { mode: "bangla" });
+// → "17th Chaitra 1432"
+
+format("2026-03-31", { mode: "bangla", locale: "bn-BD" });
+// → "১৭ই চৈত্র ১৪৩২ বঙ্গাব্দ"
+
+format("2026-04-14", { mode: "bangla", locale: "bn-BD" });
 // → "১লা বৈশাখ ১৪৩৩"
 
-formatDate(new Date(2026, 2, 31, 15, 4), {
-  weekday: "short",
-  hour: "numeric",
-  minute: "2-digit"
-});
-// → "Tue, 31 Mar 2026, 15:04"
-
-formatDate(new Date(2026, 2, 31, 21, 4, 9), {
-  weekday: "long",
-  hour: "2-digit",
-  minute: "2-digit",
-  second: "2-digit",
-  hour12: true
-});
-// → "Tuesday, 31 Mar 2026, 09:04:09 PM"
-
+toHijriCalendar("2026-03-31");
+// → { day: 11, month: "Shawwal", monthIndex: 10, year: 1447 }
+
+toHijriCalendar("2026-03-31", { locale: "bn-BD" });
+// → { day: "১১", month: "শাওয়াল", monthIndex: 10, year: "১৪৪৭" }
+
+toHijriCalendar("2026-03-31", { timeZone: "UTC" });
+// → { day: 11, month: "Shawwal", monthIndex: 10, year: 1447 }
+
+format("2026-03-31", { mode: "hijri" });
+// → "12th Shawwal 1447 AH"
+
+format("2026-03-31", { mode: "hijri", timeZone: "UTC" });
+// → "11th Shawwal 1447 AH"
+
+| Timezone support | Details |
+| ---------------- | ------- |
+| `timeZone` | Accepts `Asia/Dhaka` and `UTC` |
+| Supported list | Exported as `HIJRI_TIME_ZONES` |
+
+format("2026-03-31", { mode: "hijri", locale: "bn-BD" });
+// → "১২ই শাওয়াল ১৪৪৭ হিজরি"
+
+format(new Date(2026, 2, 31, 15, 4), {
+  mode: "standard",
+  weekday: "short",
+  hour: "numeric",
+  minute: "2-digit"
+});
+// → "Tue, 31st Mar 2026, 15:04"
+
+format(new Date(2026, 2, 31, 21, 4, 9), {
+  mode: "standard",
+  weekday: "long",
+  hour: "2-digit",
+  minute: "2-digit",
+  second: "2-digit",
+  hour12: true
+});
+// → "Tuesday, 31st Mar 2026, 09:04:09 PM"
+
 fromNow(new Date(Date.now() - 86400000), { numeric: "auto" });
-// → "yesterday"
-
+// Output depends on the current clock.
+
 fromNow(new Date(), { numeric: "auto" });
-// → "today"
-```
-
-## Features
-
-### Date Formatting
-
-```ts
-import { formatDate } from "@coreify/tarikh";
-
-formatDate(new Date());
-// → "31 Mar 2026"
-
-formatDate(new Date(), { locale: "bn-BD" });
-// → "৩১ মার্চ ২০২৬"
-
-formatDate(new Date(), { month: "long", year: "2-digit" });
-// → "31 March 26"
-
-formatDate(new Date(2026, 2, 31, 15, 4, 9), {
-  weekday: "long",
-  hour: "2-digit",
-  minute: "2-digit",
-  second: "2-digit",
-  hour12: true
-});
-// → "Tuesday, 31 Mar 2026, 03:04:09 PM"
-```
-
-**Options:** `locale` (`"en-BD"` | `"bn-BD"`), `month` (`"short"` | `"long"`), `year` (`"numeric"` | `"2-digit"`), `day` (`"numeric"` | `"2-digit"`), `weekday` (`"short"` | `"long"`), `hour` / `minute` / `second` (`"numeric"` | `"2-digit"`), `hour12` (`boolean`)
-
-### Token-based Formatting
-
-```ts
-import { format } from "@coreify/tarikh";
-
-format(new Date(), "DD MMM YYYY");
-// → "31 Mar 2026"
-
-format(new Date(), "DD MMMM YYYY", { locale: "bn-BD" });
-// → "৩১ মার্চ ২০২৬"
-
-format(new Date(), "DD/MM/YYYY");
-// → "31/03/2026"
-
-format(new Date(2026, 2, 31, 15, 4, 9), "ddd, D MMM YYYY HH:mm:ss");
-// → "Tue, 31 Mar 2026 15:04:09"
-
-format(new Date(2026, 2, 31, 9, 4), "ddd, D MMM YYYY h:mm a", {
-  locale: "bn-BD"
-});
-// → "মঙ্গল, ৩১ মার্চ ২০২৬ ৯:০৪ পূর্বাহ্ণ"
-
-format(new Date(2026, 2, 31, 21, 4, 9), "dddd, D MMM YYYY hh:mm:ss A");
-// → "Tuesday, 31 Mar 2026 09:04:09 PM"
-```
-
-**Tokens:** `dddd`, `ddd`, `DD`, `D`, `MMMM`, `MMM`, `MM`, `M`, `YYYY`, `YY`, `HH`, `H`, `hh`, `h`, `mm`, `m`, `ss`, `s`, `A`, `a`
-
-### Bangla Calendar
-
-Convert Gregorian dates to the Bengali calendar (Bangladesh Revised Calendar, 1987).
-
-- `toBanglaCalendar()` returns a structured object.
-- Default output: English digits + Latin month names (`en-BD`).
-- Locale-aware output: Bangla date words like `১লা`, `২রা`, `৩রা`, `৪ঠা`, `৫ই`, `১৯শে` plus Bangla month names (`bn-BD`).
-- `monthIndex` remains numeric in both cases.
-- `formatBanglaCalendar(..., { locale: "bn-BD", format: "spoken" })` returns spoken day words like `পহেলা`, `দোসরা`, `তেসরা`, `চৌঠা`.
-- `formatBanglaCalendarDay(day, { format: "spoken" })` returns colloquial spoken forms for the first four days: `পহেলা`, `দোসরা`, `তেসরা`, `চৌঠা`.
-- Pass `{ variant: "pohela" }` to keep the standard `পহেলা` spelling explicitly, or `{ variant: "poyla" }` to get `পয়লা` for day 1. The parser also accepts the common `পয়লা` spelling.
+// Output depends on the current clock.
+```
+
+> Use `format()` for everything. Choose a mode (`standard`, `bangla`, `hijri`, `hybrid`) or pass a token pattern.
+
+```ts
+// Show today's Bangla date in your app header
+format("2026-03-31", { mode: "bangla", locale: "bn-BD" });
+// → "১৭ চৈত্র ১৪৩২ বঙ্গাব্দ"
+```
+
+## Features
+
+### Standard Formatting
+
+```ts
+import { format } from "@coreify/tarikh";
+
+format("2026-03-31", { mode: "standard" });
+// → "31st Mar 2026"
+
+format("2026-03-31", { mode: "standard", locale: "bn-BD" });
+// → "৩১শে মার্চ ২০২৬ খ্রিস্টাব্দ"
+
+format("2026-03-31", { mode: "standard", month: "long", year: "2-digit" });
+// → "31st March 26"
+
+format(new Date(2026, 2, 31, 15, 4, 9), {
+  mode: "standard",
+  weekday: "long",
+  hour: "2-digit",
+  minute: "2-digit",
+  second: "2-digit",
+  hour12: true
+});
+// → "Tuesday, 31st Mar 2026, 03:04:09 PM"
+```
+
+**Options:** `locale` (`"en-BD"` | `"bn-BD"`), `month` (`"short"` | `"long"`), `year` (`"numeric"` | `"2-digit"`), `day` (`"numeric"` | `"2-digit"`), `weekday` (`"short"` | `"long"`), `hour` / `minute` / `second` (`"numeric"` | `"2-digit"`), `hour12` (`boolean`)
+
+### Pattern Formatting
+
+```ts
+import { format } from "@coreify/tarikh";
+
+format("2026-03-31", { pattern: "DD MMM YYYY" });
+// → "31 Mar 2026"
+
+format("2026-03-31", { pattern: "DD MMMM YYYY", locale: "bn-BD" });
+// → "৩১ মার্চ ২০২৬"
+
+format("2026-03-31", { pattern: "DD/MM/YYYY" });
+// → "31/03/2026"
+
+format(new Date(2026, 2, 31, 15, 4, 9), {
+  pattern: "ddd, D MMM YYYY HH:mm:ss"
+});
+// → "Tue, 31 Mar 2026 15:04:09"
+
+format(new Date(2026, 2, 31, 9, 4), {
+  pattern: "ddd, D MMM YYYY h:mm a",
+  locale: "bn-BD"
+});
+// → "মঙ্গল, ৩১ মার্চ ২০২৬ ৯:০৪ পূর্বাহ্ণ"
+
+format(new Date(2026, 2, 31, 21, 4, 9), {
+  pattern: "dddd, D MMM YYYY hh:mm:ss A"
+});
+// → "Tuesday, 31 Mar 2026 09:04:09 PM"
+```
+
+> `format()` is the primary API. Use `{ mode }` for date behavior or `{ pattern }` for token formatting. `mode` and `pattern` are mutually exclusive.
+
+**Tokens:** `dddd`, `ddd`, `DD`, `D`, `MMMM`, `MMM`, `MM`, `M`, `YYYY`, `YY`, `HH`, `H`, `hh`, `h`, `mm`, `m`, `ss`, `s`, `A`, `a`
+
+> Use square brackets to keep literal text untouched by token replacement:
+
+```ts
+format(new Date(2026, 2, 31, 15, 4), { pattern: "[Today at] h:mm a" });
+// → "Today at 3:04 pm"
+```
+
+> Bracket literals are not nestable; the first `]` closes the literal block.
+
+## 🇧🇩 Bangla Calendar (Core Feature)
+
+| Bangla calendar | Behavior |
+| --------------- | -------- |
+| `toBanglaCalendar()` | Returns a structured object |
+| Default output | English digits + Latin month names (`en-BD`) |
+| `bn-BD` output | Bangla day forms like `১লা`, `২রা`, `৩রা`, `৪ঠা`, `৫ই`, `১৯শে` |
+| Spoken mode | Returns `পহেলা`, `দোসরা`, `তেসরা`, `চৌঠা` |
+| `variant: "pohela"` | Keeps the standard `পহেলা` spelling |
+| `variant: "poyla"` | Uses `পয়লা` for day 1 |
+| `monthIndex` | Stays numeric in both cases |
 
 ```ts
 import {
-  formatBanglaCalendar,
-  formatBanglaCalendarDay,
-  toBanglaCalendar
-} from "@coreify/tarikh";
-
-toBanglaCalendar("2026-03-31");
-// → { day: 17, month: "Chaitra", monthIndex: 12, year: 1432 }
-
-toBanglaCalendar("2026-03-31", { locale: "bn-BD" });
-// → { day: "১৭", month: "চৈত্র", monthIndex: 12, year: "১৪৩২" }
-
-formatBanglaCalendar("2026-03-31");
-// → "17 Chaitra 1432"
-
-formatBanglaCalendar("2026-03-31", { locale: "bn-BD" });
-// → "১৭ই চৈত্র ১৪৩২"
-
-formatBanglaCalendar("2026-04-14");
-// → "1 Baishakh 1433"
-
-formatBanglaCalendar("2026-04-14", { locale: "bn-BD", format: "spoken" });
-// → "পহেলা বৈশাখ ১৪৩৩"
-
-formatBanglaCalendar("2026-04-14", {
-  locale: "bn-BD",
-  format: "spoken",
-  variant: "poyla"
-});
-// → "পয়লা বৈশাখ ১৪৩৩"
-
-formatBanglaCalendarDay(21);
-// → "২১শে"
-
-formatBanglaCalendarDay(1, { format: "spoken" });
-// → "পহেলা"
-
-formatBanglaCalendarDay(1, { format: "spoken", variant: "poyla" });
-// → "পয়লা"
-
+  format,
+  formatBanglaCalendarDay,
+  toBanglaCalendar
+} from "@coreify/tarikh";
+
+toBanglaCalendar("2026-03-31");
+// → { day: 17, month: "Chaitra", monthIndex: 12, year: 1432 }
+
+toBanglaCalendar("2026-03-31", { locale: "bn-BD" });
+// → { day: "১৭", month: "চৈত্র", monthIndex: 12, year: "১৪৩২" }
+
+format("2026-03-31", { mode: "bangla" });
+// → "17th Chaitra 1432"
+
+format("2026-03-31", { mode: "bangla", locale: "bn-BD" });
+// → "১৭ই চৈত্র ১৪৩২ বঙ্গাব্দ"
+
+format("2026-04-14", { mode: "bangla" });
+// → "1st Baishakh 1433"
+
+format("2026-04-14", { mode: "bangla", locale: "bn-BD", format: "spoken" });
+// → "পহেলা বৈশাখ ১৪৩৩ বঙ্গাব্দ"
+
+format("2026-04-14", {
+  mode: "bangla",
+  locale: "bn-BD",
+  format: "spoken",
+  variant: "poyla"
+});
+// → "পয়লা বৈশাখ ১৪৩৩ বঙ্গাব্দ"
+
+// Show today's Bangla date in your app header
+format("2026-03-31", { mode: "bangla", locale: "bn-BD" });
+// → "১৭ চৈত্র ১৪৩২ বঙ্গাব্দ" (example; depends on the current date)
+
+formatBanglaCalendarDay(21);
+// → "২১শে"
+
+formatBanglaCalendarDay(1, { format: "spoken" });
+// → "পহেলা"
+
+formatBanglaCalendarDay(1, { format: "spoken", variant: "poyla" });
+// → "পয়লা"
+
 formatBanglaCalendarDay(1, { format: "spoken", variant: "pohela" });
 // → "পহেলা"
 ```
 
-### Hybrid Formatting
+### Hijri Calendar
 
-Mix English and Bangla independently for day, month, and year.
+| Hijri calendar | Behavior |
+| -------------- | -------- |
+| `toHijriCalendar()` | Returns a structured object |
+| Default timezone | `Asia/Dhaka` |
+| `timeZone` override | Accepts the exported `HIJRI_TIME_ZONES` values |
+| Default output | English month/day/year with `AH` |
+| `bn-BD` output | Bangla digits and the `হিজরি` suffix |
+| `UTC` override | Exposes the alternative canonical Hijri result |
 
 ```ts
-import { formatHybridDate } from "@coreify/tarikh";
+import { HIJRI_TIME_ZONES, format, toHijriCalendar } from "@coreify/tarikh";
 
-formatHybridDate(new Date());
-// → "31 মার্চ 2026"
+const [defaultHijriZone, alternateHijriZone] = HIJRI_TIME_ZONES;
 
-formatHybridDate(new Date(), { digits: "bn", month: "bn", year: "en" });
-// → "৩১ মার্চ 2026"
-```
+toHijriCalendar("2026-03-31");
+// → { day: 11, month: "Shawwal", monthIndex: 10, year: 1447 }
 
-### Bangla Digits
+toHijriCalendar("2026-03-31", { locale: "bn-BD" });
+// → { day: "১১", month: "শাওয়াল", monthIndex: 10, year: "১৪৪৭" }
 
-```ts
-import { toBanglaDigits, toEnglishDigits } from "@coreify/tarikh";
+toHijriCalendar("2026-03-31", { timeZone: "UTC" });
+// → { day: 11, month: "Shawwal", monthIndex: 10, year: 1447 }
 
-toBanglaDigits("31 March 2026");
-// → "৩১ March ২০২৬"
+// Supported values: defaultHijriZone === "Asia/Dhaka", alternateHijriZone === "UTC"
 
-toEnglishDigits("৩১ মার্চ ২০২৬");
-// → "31 মার্চ 2026"
-```
+format("2026-03-31", { mode: "hijri" });
+// → "12th Shawwal 1447 AH"
 
-### Relative Time
+format("2026-03-31", { mode: "hijri", timeZone: "UTC" });
+// → "11th Shawwal 1447 AH"
 
-```ts
-import { fromNow } from "@coreify/tarikh";
+format("2026-03-31", { mode: "hijri", locale: "bn-BD" });
+// → "১২ই শাওয়াল ১৪৪৭ হিজরি"
+```
 
+### Hybrid Formatting
+
+| Mixing rule | Summary |
+| ----------- | ------- |
+| Hybrid formatting | Mix English and Bangla independently for day, month, and year |
+
+```ts
+import { format } from "@coreify/tarikh";
+
+format("2026-03-31", { mode: "hybrid" });
+// → "31 মার্চ 2026"
+
+format("2026-03-31", {
+  mode: "hybrid",
+  digits: "bn",
+  month: "bn",
+  year: "en"
+});
+// → "৩১ মার্চ 2026"
+```
+
+### Bangla Digits
+
+```ts
+import { toBanglaDigits, toEnglishDigits } from "@coreify/tarikh";
+
+toBanglaDigits("31 March 2026");
+// → "৩১ March ২০২৬"
+
+toEnglishDigits("৩১ মার্চ ২০২৬");
+// → "31 মার্চ 2026"
+```
+
+### Relative Time
+
+```ts
+import { fromNow } from "@coreify/tarikh";
+
 fromNow(new Date(Date.now() - 86400000));
-// → "1 day ago"
-
+// Output depends on the current clock.
+
 fromNow(new Date(Date.now() - 86400000), { locale: "bn-BD" });
-// → "১ দিন আগে"
-
+// Output depends on the current clock.
+
 fromNow(new Date(Date.now() + 3600000));
-// → "in 1 hour"
-
+// Output depends on the current clock.
+
 fromNow(new Date(Date.now() - 86400000), { numeric: "auto" });
-// → "yesterday"
-
+// Output depends on the current clock.
+
 fromNow(new Date(Date.now() + 86400000), {
   locale: "bn-BD",
   numeric: "auto"
 });
-// → "আগামীকাল"
-```
-
-### Parsing
-
-```ts
-import { parseDate } from "@coreify/tarikh";
-
-parseDate("৩১ মার্চ ২০২৬");
-// → Date object (March 31, 2026)
-
-parseDate("17 Chaitra 1432", { calendar: "bangla" });
-// → Date object (March 31, 2026)
-
-// Legacy spellings (Boishakh, Joishtho, Choitro, etc.) are still accepted.
-
-parseDate("১৭ চৈত্র ১৪৩২", { calendar: "bangla" });
-// → Date object (March 31, 2026)
-
-parseDate("31 March 2026");
-// → Date object (March 31, 2026)
-
-parseDate("March 31, 2026");
-// → Date object (March 31, 2026)
-
-parseDate("31-Mar-2026");
-// → Date object (March 31, 2026)
-
-parseDate("2026/03/31");
-// → Date object (March 31, 2026)
-
-parseDate("2026.03.31");
-// → Date object (March 31, 2026)
-
-parseDate("2026-03-31T15:30:00Z");
-// → Date object (March 31, 2026, 3:30 PM UTC)
-
-// `toDate()` accepts the same Gregorian string forms as `parseDate()`,
-// plus `Date` objects and timestamps.
-// Supported string shapes:
-// - `YYYY-MM-DD`
-// - `YYYY/MM/DD`
-// - `YYYY.MM.DD`
-// - `YYYY-M-D`, `YYYY/M/D`, `YYYY.M.D`
-// - `YYYY-MM-DDTHH:mm[:ss[.fraction]][Z|±HH:mm]`
-// - `DD Month YYYY`
-// - `Month DD, YYYY`
-// - `DD-Month-YYYY`
-// - Bangla calendar strings like `১৭ চৈত্র ১৪৩২`
-// - Common Bangla month aliases like `Boishakh`, `Poush`, `Falgun`, `Asharh`
-```
-
-### Utilities
-
-```ts
-import {
-  isToday,
-  isYesterday,
-  isTomorrow,
-  startOfDay,
-  endOfDay,
-  startOfMonth,
-  endOfMonth,
-  startOfYear,
-  endOfYear,
-  addDays,
-  subDays,
-  addMonths,
-  subMonths,
-  addYears,
-  subYears,
-  getBanglaMonth
-} from "@coreify/tarikh";
-
-isToday(new Date()); // → true
-isYesterday(subDays(new Date(), 1)); // → true
-isTomorrow(addDays(new Date(), 1)); // → true
-startOfMonth(new Date()); // → Date at the start of this month
-endOfMonth(new Date()); // → Date at the end of this month
-addMonths("2026-01-31", 1); // → 2026-02-28
-addYears(new Date(2024, 1, 29), 1); // → 2025-02-28
-
-getBanglaMonth(3); // → "মার্চ"
-getBanglaMonth(3, "short"); // → "মার্চ"
-getBanglaMonth(12); // → "ডিসেম্বর"
-```
-
-### Constants
-
-```ts
-import {
-  BANGLA_MONTHS_FULL,
-  BANGLA_MONTHS_SHORT,
-  BANGLA_CALENDAR_MONTHS,
-  BANGLA_CALENDAR_MONTHS_EN,
-  BANGLA_WEEKDAYS_FULL,
-  BANGLA_WEEKDAYS_SHORT,
-  ENGLISH_WEEKDAYS_FULL,
-  ENGLISH_WEEKDAYS_SHORT,
-  BANGLA_DIGITS,
-  ENGLISH_DIGITS
-} from "@coreify/tarikh";
-```
-
+// Output depends on the current clock.
+```
+
+### Parsing
+
+```ts
+import { parseDate } from "@coreify/tarikh";
+
+parseDate("৩১ মার্চ ২০২৬");
+// → Date object (March 31, 2026)
+
+parseDate("17 Chaitra 1432", { calendar: "bangla" });
+// → Date object (March 31, 2026)
+
+// Legacy spellings (Boishakh, Joishtho, Choitro, etc.) are still accepted.
+
+parseDate("১৭ চৈত্র ১৪৩২", { calendar: "bangla" });
+// → Date object (March 31, 2026)
+
+parseDate("31 March 2026");
+// → Date object (March 31, 2026)
+
+parseDate("March 31, 2026");
+// → Date object (March 31, 2026)
+
+parseDate("31-Mar-2026");
+// → Date object (March 31, 2026)
+
+parseDate("2026/03/31");
+// → Date object (March 31, 2026)
+
+parseDate("2026.03.31");
+// → Date object (March 31, 2026)
+
+parseDate("2026-03-31T15:30:00Z");
+// → Date object (March 31, 2026, 3:30 PM UTC)
+
+// `toDate()` accepts the same Gregorian string forms as `parseDate()`,
+// plus `Date` objects and timestamps.
+// Supported string shapes:
+// - `YYYY-MM-DD`
+// - `YYYY/MM/DD`
+// - `YYYY.MM.DD`
+// - `YYYY-M-D`, `YYYY/M/D`, `YYYY.M.D`
+// - `YYYY-MM-DDTHH:mm[:ss[.fraction]][Z|±HH:mm]`
+// - `DD Month YYYY`
+// - `Month DD, YYYY`
+// - `DD-Month-YYYY`
+// - Bangla calendar strings like `১৭ চৈত্র ১৪৩২`
+// - Common Bangla month aliases like `Boishakh`, `Poush`, `Falgun`, `Asharh`
+```
+
+### Utilities
+
+```ts
+import {
+  isToday,
+  isYesterday,
+  isTomorrow,
+  startOfDay,
+  endOfDay,
+  startOfMonth,
+  endOfMonth,
+  startOfYear,
+  endOfYear,
+  addDays,
+  subDays,
+  addMonths,
+  subMonths,
+  addYears,
+  subYears,
+  getBanglaMonth
+} from "@coreify/tarikh";
+
+isToday(new Date()); // → true
+isYesterday(subDays(new Date(), 1)); // → true
+isTomorrow(addDays(new Date(), 1)); // → true
+startOfMonth(new Date()); // → Date at the start of this month
+endOfMonth(new Date()); // → Date at the end of this month
+addMonths("2026-01-31", 1); // → 2026-02-28
+addYears(new Date(2024, 1, 29), 1); // → 2025-02-28
+
+getBanglaMonth(3); // → "মার্চ"
+getBanglaMonth(3, "short"); // → "মার্চ"
+getBanglaMonth(12); // → "ডিসেম্বর"
+```
+
+### Constants
+
+```ts
+import {
+  BANGLA_MONTHS_FULL,
+  BANGLA_MONTHS_SHORT,
+  BANGLA_CALENDAR_MONTHS,
+  BANGLA_CALENDAR_MONTHS_EN,
+  BANGLA_WEEKDAYS_FULL,
+  BANGLA_WEEKDAYS_SHORT,
+  ENGLISH_WEEKDAYS_FULL,
+  ENGLISH_WEEKDAYS_SHORT,
+  BANGLA_DIGITS,
+  ENGLISH_DIGITS
+} from "@coreify/tarikh";
+```
+
 ## React Components
 
-Optional entry point — only included if you import from `@coreify/tarikh/react`.
+| React export | Purpose |
+| ------------ | ------- |
+| `Tarikh` | Default semantic `<time>` formatter |
+| `Tarikh.Relative` | Relative time rendering |
+| `Tarikh.Bangla` | Bangla calendar rendering |
+| `Tarikh.Hijri` | Hijri calendar rendering |
 
-```bash
-npm install @coreify/tarikh react
-```
-
-### Tarikh
+> Import from `@coreify/tarikh/react` only when you need the React components.
 
 ```tsx
 import { Tarikh } from "@coreify/tarikh/react";
 
-<Tarikh value={new Date()} />
-// → <time>31 Mar 2026</time>
-
-<Tarikh value={new Date()} locale="bn-BD" />
-// → <time>৩১ মার্চ ২০২৬</time>
-
-<Tarikh value={new Date()} month="long" />
-// → <time>31 March 2026</time>
-
-<Tarikh
-  value={new Date(2026, 2, 31, 15, 4)}
-  weekday="short"
-  hour="numeric"
-  minute="2-digit"
-/>
-// → <time>Tue, 31 Mar 2026, 15:04</time>
-
-<Tarikh
-  value={new Date(2026, 2, 31, 15, 4, 9)}
-  weekday="long"
-  hour="2-digit"
-  minute="2-digit"
-  second="2-digit"
-  hour12
-  locale="bn-BD"
-/>
-// → <time>মঙ্গলবার, ৩১ মার্চ ২০২৬, ০৩:০৪:০৯ অপরাহ্ণ</time>
-
-<Tarikh value="31 March 2026" />
-// → <time dateTime="2026-03-31">31 Mar 2026</time>
-```
-
-### RelativeTime
+const date = "2026-03-31";
 
-```tsx
-import { RelativeTime } from "@coreify/tarikh/react";
-
-<RelativeTime value={someDate} />
-// → <time>2 days ago</time>
-
-<RelativeTime value={someDate} locale="bn-BD" />
-// → <time>২ দিন আগে</time>
-
-<RelativeTime value={someDate} numeric="auto" />
-// → <time>yesterday</time> (for a 1-day past date)
-
-<RelativeTime value={someDate} locale="bn-BD" numeric="auto" />
-// → <time>আগামীকাল</time> (for a 1-day future date)
+<Tarikh value={date} />
+<Tarikh.Relative value={date} />
+<Tarikh.Bangla value={date} locale="bn-BD" />
+<Tarikh.Hijri value={date} locale="bn-BD" />
 ```
-
-### BanglaDate
-
-```tsx
-import { BanglaDate } from "@coreify/tarikh/react";
-
-<BanglaDate value={new Date()} />
-// → <time>17 Chaitra 1432</time> (example; depends on date)
-
-<BanglaDate value={new Date()} locale="bn-BD" />
-// → <time>১৭ই চৈত্র ১৪৩২</time> (example; depends on date)
-
-<BanglaDate
-  value={new Date()}
-  locale="bn-BD"
-  format="spoken"
-  variant="poyla"
-/>
-// → spoken day + Bangla month (e.g. পয়লা বৈশাখ … on Pohela Baishakh)
-
-<BanglaDate value="31 March 2026" />
-// → <time dateTime="2026-03-31">17 Chaitra 1432</time> (example; depends on date)
-```
-
-All components render semantic `<time>` elements with `dateTime` and `aria-label` attributes. They are SSR-safe, tree-shakeable, and have zero runtime dependencies beyond React.
-
+
+```bash
+npm install @coreify/tarikh react
+```
+
+| React detail | Notes |
+| ------------ | ----- |
+| Semantics | Renders `<time>` elements with `dateTime` and `aria-label` |
+| Runtime | SSR-safe, tree-shakeable, zero runtime dependencies beyond React |
+| Roles | `Tarikh` standard formatting, `Tarikh.Relative` relative time, `Tarikh.Bangla` Bangla calendar, `Tarikh.Hijri` Hijri calendar |
+
 ## What `Intl.DateTimeFormat` cannot do
 
+| Why `Intl` falls short | Summary |
+| --------------------- | ------- |
+| Bangladesh-focused formatting | Needs Bangla calendar and culturally correct output |
+
 | Feature                         | Intl    | @coreify/tarikh |
 | ------------------------------- | ------- | --------------- |
 | Bangla calendar (বৈশাখ → চৈত্র) | No      | Yes             |
+| Hijri calendar                  | Partial | Yes             |
 | Bangla digits in dates          | Partial | Yes             |
-| Hybrid formatting (mixed en/bn) | No      | Yes             |
-| Bangla calendar date parsing    | No      | Yes             |
-| Relative time in Bangla         | No      | Yes             |
-| SSR-safe React components       | N/A     | Yes             |
-
+| Hybrid formatting (mixed en/bn) | No      | Yes             |
+| Bangla calendar date parsing    | No      | Yes             |
+| Relative time in Bangla         | No      | Yes             |
+| SSR-safe React components       | N/A     | Yes             |
+
 ## TypeScript
 
-Fully typed with strict mode. Core option interfaces and value types are exported from `@coreify/tarikh`.
+| Type | Purpose |
+| ---- | ------- |
+| `FormatOptions` | Primary object-based formatting contract |
+| `TarikhProps` | Props for the main React `<Tarikh />` component |
+| `HIJRI_TIME_ZONES` | Canonical supported Hijri time zones (`Asia/Dhaka`, `UTC`) |
+| Type-level contract | When using `pattern`, `mode` is intentionally disallowed in TypeScript |
 
 ```ts
 import type {
-  DateInput,
-  DayFormat,
-  MonthFormat,
-  Locale,
-  Language,
-  YearFormat,
-  WeekdayFormat,
-  TimeFormat,
-  BanglaCalendarOptions,
-  RelativeTimeOptions,
-  BanglaCalendarFormatOptions,
-  BanglaCalendarDayFormat,
-  BanglaCalendarDaySpokenVariant,
-  BanglaDayFormatOptions,
-  DateFormatOptions,
-  BanglaCalendarDate,
-  HybridDateFormatOptions
-} from "@coreify/tarikh";
-```
-
-```ts
-import type {
-  BanglaDateProps,
-  RelativeTimeProps,
-  TarikhProps
-} from "@coreify/tarikh/react";
-```
-
-## License
-
-MIT
+  Locale,
+  FormatMode,
+  FormatOptions,
+  DateInput,
+  RelativeTimeOptions
+} from "@coreify/tarikh";
+
+import type { TarikhProps } from "@coreify/tarikh/react";
+```
+
+## License
+
+MIT