@coreify/tarikh 1.0.1 → 1.1.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Coreify
-
-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.
+MIT License
+
+Copyright (c) 2026 Coreify
+
+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

@@ -4,37 +4,55 @@
 [![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 full Bangla calendar support.
-
-Built for Bangla dates, Bengali calendar conversion, and culturally correct formatting.
+> 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          |
+| `setDefaults()` / `getDefaults()` | Configure reusable package-wide defaults                 |
+| `parseDateDetailed()`             | Parse with structured success/failure metadata           |
+| `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
 
-External demo: [tarikh.js.org](https://tarikh.js.org)
+| 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
+| 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.                     |
+| Global defaults      | Reuse locale, mode, month, Hijri timezone, and Hijri backend across an app |
+| 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.
+> `@coreify/tarikh` is a zero-dependency, tree-shakeable, SSR-safe toolkit purpose-built for Bangladesh.
 
 ## Installation
 
@@ -46,20 +64,44 @@ npm install @coreify/tarikh
 
 ```ts
 import {
+  HIJRI_TIME_ZONES,
   format,
   fromNow,
-  toBanglaCalendar
+  getDefaults,
+  parseDateDetailed,
+  setDefaults,
+  toBanglaCalendar,
+  toHijriCalendar
 } from "@coreify/tarikh";
 
+const [defaultHijriZone, utcHijriZone] = HIJRI_TIME_ZONES;
+
 // Preferred entry points:
-format(new Date(), { mode: "standard" });
-format(new Date(), { mode: "bangla" });
-format(new Date(), { mode: "hybrid" });
+format("2026-03-31", { mode: "standard" });
+format("2026-03-31", { mode: "bangla" });
+format("2026-03-31", { mode: "hijri" });
+format("2026-03-31", { mode: "hybrid" });
+
+setDefaults({ locale: "bn-BD", mode: "standard", month: "long" });
+getDefaults();
+// → { locale: "bn-BD", mode: "standard", month: "long", timeZone: "Asia/Dhaka", hijriSystem: "islamic-umalqura" }
 
 // Token-based output still works.
-format(new Date(), { pattern: "DD MMM YYYY" });
+format("2026-03-31", { pattern: "DD MMM YYYY" });
 // → "31 Mar 2026"
 
+format(new Date(2026, 2, 31, 15, 4, 9), {
+  mode: "standard",
+  preset: "dateTime"
+});
+// → "31st Mar 2026, 15:04"
+
+format(new Date(2026, 2, 31, 15, 4, 9), {
+  mode: "standard",
+  preset: "isoLike"
+});
+// → "2026-03-31 15:04:09"
+
 // Structured Bangla calendar conversion
 // `monthIndex` stays numeric; `bn-BD` localizes `day`, `month`, and `year`.
 toBanglaCalendar("2026-03-31");
@@ -68,22 +110,64 @@ toBanglaCalendar("2026-03-31");
 toBanglaCalendar("2026-03-31", { locale: "bn-BD" });
 // → { day: "১৭", month: "চৈত্র", monthIndex: 12, year: "১৪৩২" }
 
+const dynamicLocale: "en-BD" | "bn-BD" =
+  Math.random() > 0.5 ? "en-BD" : "bn-BD";
+const structuredBangla = toBanglaCalendar("2026-03-31", {
+  locale: dynamicLocale
+});
+// → BanglaCalendarResult<"en-BD" | "bn-BD">
+
+const locale: "en-BD" | "bn-BD" = Math.random() > 0.5 ? "en-BD" : "bn-BD";
+const structuredBangla = toBanglaCalendar("2026-03-31", { locale });
+// → TypeScript infers BanglaCalendarResult<"en-BD" | "bn-BD">
+
 format("2026-03-31", { mode: "bangla" });
-// → "17 Chaitra 1432"
+// → "17th Chaitra 1432"
 
 format("2026-03-31", { mode: "bangla", locale: "bn-BD" });
-// → "১৭ই চৈত্র ১৪৩২"
+// → "১৭ই চৈত্র ১৪৩২ বঙ্গাব্দ"
 
 format("2026-04-14", { mode: "bangla", locale: "bn-BD" });
 // → "১লা বৈশাখ ১৪৩৩"
 
+toHijriCalendar("2026-03-31");
+// → { day: 11, month: "Shawwal", monthIndex: 10, year: 1447 }
+
+toHijriCalendar("2026-03-31", { locale: "bn-BD" });
+// → { day: "১১", month: "শাওয়াল", monthIndex: 10, year: "১৪৪৭" }
+
+const structuredHijri = toHijriCalendar("2026-03-31", {
+  locale: dynamicLocale
+});
+// → HijriCalendarResult<"en-BD" | "bn-BD">
+
+const structuredHijri = toHijriCalendar("2026-03-31", { locale });
+// → TypeScript infers HijriCalendarResult<"en-BD" | "bn-BD">
+
+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, 31 Mar 2026, 15:04"
+// → "Tue, 31st Mar 2026, 15:04"
 
 format(new Date(2026, 2, 31, 21, 4, 9), {
   mode: "standard",
@@ -93,21 +177,30 @@ format(new Date(2026, 2, 31, 21, 4, 9), {
   second: "2-digit",
   hour12: true
 });
-// → "Tuesday, 31 Mar 2026, 09:04:09 PM"
+// → "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"
+// Output depends on the current clock.
+
+fromNow("2026-03-31T10:00:00Z", {
+  baseDate: "2026-03-31T12:00:00Z",
+  style: "short"
+});
+// → "2h ago"
+
+parseDateDetailed("31 Mar 26", { strict: true });
+// → { success: false, reason: "strict_mismatch", ... }
 ```
 
-Use `format()` for everything. Choose a mode (`standard`, `bangla`, `hybrid`) or pass a token pattern.
+> 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(new Date(), { mode: "bangla", locale: "bn-BD" });
-// → "১৭ চৈত্র ১৪৩২"
+format("2026-03-31", { mode: "bangla", locale: "bn-BD" });
+// → "১৭ চৈত্র ১৪৩২ বঙ্গাব্দ"
 ```
 
 ## Features
@@ -117,14 +210,14 @@ format(new Date(), { mode: "bangla", locale: "bn-BD" });
 ```ts
 import { format } from "@coreify/tarikh";
 
-format(new Date(), { mode: "standard" });
-// → "31 Mar 2026"
+format("2026-03-31", { mode: "standard" });
+// → "31st Mar 2026"
 
-format(new Date(), { mode: "standard", locale: "bn-BD" });
-// → "৩১ মার্চ ২০২৬"
+format("2026-03-31", { mode: "standard", locale: "bn-BD" });
+// → "৩১শে মার্চ ২০২৬ খ্রিস্টাব্দ"
 
-format(new Date(), { mode: "standard", month: "long", year: "2-digit" });
-// → "31 March 26"
+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",
@@ -134,23 +227,25 @@ format(new Date(2026, 2, 31, 15, 4, 9), {
   second: "2-digit",
   hour12: true
 });
-// → "Tuesday, 31 Mar 2026, 03:04:09 PM"
+// → "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`)
 
+**Presets:** `preset: "date" | "dateTime" | "isoLike"`
+
 ### Pattern Formatting
 
 ```ts
 import { format } from "@coreify/tarikh";
 
-format(new Date(), { pattern: "DD MMM YYYY" });
+format("2026-03-31", { pattern: "DD MMM YYYY" });
 // → "31 Mar 2026"
 
-format(new Date(), { pattern: "DD MMMM YYYY", locale: "bn-BD" });
+format("2026-03-31", { pattern: "DD MMMM YYYY", locale: "bn-BD" });
 // → "৩১ মার্চ ২০২৬"
 
-format(new Date(), { pattern: "DD/MM/YYYY" });
+format("2026-03-31", { pattern: "DD/MM/YYYY" });
 // → "31/03/2026"
 
 format(new Date(2026, 2, 31, 15, 4, 9), {
@@ -170,33 +265,30 @@ format(new Date(2026, 2, 31, 21, 4, 9), {
 // → "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.
+> `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:
+> 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.
+> Bracket literals are not nestable; the first `]` closes the literal block.
 
 ## 🇧🇩 Bangla Calendar (Core Feature)
 
-This is the reason `@coreify/tarikh` exists.
-
-Convert Gregorian dates to the Bengali calendar (Bangladesh Revised Calendar, 1987).
-
-- **Top feature:** `format("2026-04-14", { mode: "bangla", locale: "bn-BD", format: "spoken" })` returns `পহেলা বৈশাখ ১৪৩৩`.
-- `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.
-- `format(..., { mode: "bangla", 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.
+| 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 {
@@ -212,16 +304,16 @@ toBanglaCalendar("2026-03-31", { locale: "bn-BD" });
 // → { day: "১৭", month: "চৈত্র", monthIndex: 12, year: "১৪৩২" }
 
 format("2026-03-31", { mode: "bangla" });
-// → "17 Chaitra 1432"
+// → "17th Chaitra 1432"
 
 format("2026-03-31", { mode: "bangla", locale: "bn-BD" });
-// → "১৭ই চৈত্র ১৪৩২"
+// → "১৭ই চৈত্র ১৪৩২ বঙ্গাব্দ"
 
 format("2026-04-14", { mode: "bangla" });
-// → "1 Baishakh 1433"
+// → "1st Baishakh 1433"
 
 format("2026-04-14", { mode: "bangla", locale: "bn-BD", format: "spoken" });
-// → "পহেলা বৈশাখ ১৪৩৩"
+// → "পহেলা বৈশাখ ১৪৩৩ বঙ্গাব্দ"
 
 format("2026-04-14", {
   mode: "bangla",
@@ -229,11 +321,11 @@ format("2026-04-14", {
   format: "spoken",
   variant: "poyla"
 });
-// → "পয়লা বৈশাখ ১৪৩৩"
+// → "পয়লা বৈশাখ ১৪৩৩ বঙ্গাব্দ"
 
 // Show today's Bangla date in your app header
-format(new Date(), { mode: "bangla", locale: "bn-BD" });
-// → "১৭ চৈত্র ১৪৩২" (example; depends on the current date)
+format("2026-03-31", { mode: "bangla", locale: "bn-BD" });
+// → "১৭ চৈত্র ১৪৩২ বঙ্গাব্দ" (example; depends on the current date)
 
 formatBanglaCalendarDay(21);
 // → "২১শে"
@@ -248,17 +340,63 @@ formatBanglaCalendarDay(1, { format: "spoken", variant: "pohela" });
 // → "পহেলা"
 ```
 
+### Hijri Calendar
+
+| Hijri calendar         | Behavior                                           |
+| ---------------------- | -------------------------------------------------- |
+| `toHijriCalendar()`    | Returns a structured object                        |
+| Default timezone       | `Asia/Dhaka`                                       |
+| `timeZone` override    | Accepts the exported `HIJRI_TIME_ZONES` values     |
+| Default backend        | `Intl` with `islamic-umalqura`                     |
+| `hijriSystem` override | Accepts `"islamic-umalqura"` and `"islamic-civil"` |
+| 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 { HIJRI_TIME_ZONES, format, toHijriCalendar } from "@coreify/tarikh";
+
+const [defaultHijriZone, alternateHijriZone] = HIJRI_TIME_ZONES;
+
+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 }
+
+toHijriCalendar("2026-03-31", { hijriSystem: "islamic-civil" });
+// → Civil Hijri output backed by Intl
+
+// Supported values: defaultHijriZone === "Asia/Dhaka", alternateHijriZone === "UTC"
+
+format("2026-03-31", { mode: "hijri" });
+// → "12th Shawwal 1447 AH"
+
+format("2026-03-31", { mode: "hijri", timeZone: "UTC" });
+// → "11th Shawwal 1447 AH"
+
+format("2026-03-31", { mode: "hijri", locale: "bn-BD" });
+// → "১২ই শাওয়াল ১৪৪৭ হিজরি"
+```
+
+> Hijri output is powered by `Intl` and defaults to `islamic-umalqura`. Regional moon-sighting expectations can differ from the returned value, so use `hijriSystem` and `timeZone` intentionally.
+
 ### Hybrid Formatting
 
-Mix English and Bangla independently for day, month, and year.
+| Mixing rule       | Summary                                                       |
+| ----------------- | ------------------------------------------------------------- |
+| Hybrid formatting | Mix English and Bangla independently for day, month, and year |
 
 ```ts
 import { format } from "@coreify/tarikh";
 
-format(new Date(), { mode: "hybrid" });
+format("2026-03-31", { mode: "hybrid" });
 // → "31 মার্চ 2026"
 
-format(new Date(), {
+format("2026-03-31", {
   mode: "hybrid",
   digits: "bn",
   month: "bn",
@@ -285,28 +423,39 @@ toEnglishDigits("৩১ মার্চ ২০২৬");
 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"
 });
-// → "আগামীকাল"
+// Output depends on the current clock.
+
+fromNow("2026-03-31T10:00:00Z", {
+  baseDate: "2026-03-31T12:00:00Z",
+  style: "short"
+});
+// → "2h ago"
+
+fromNow(new Date(Date.now() - 30000), {
+  threshold: { justNow: 60000 }
+});
+// → "just now"
 ```
 
 ### Parsing
 
 ```ts
-import { parseDate } from "@coreify/tarikh";
+import { parseDate, parseDateDetailed } from "@coreify/tarikh";
 
 parseDate("৩১ মার্চ ২০২৬");
 // → Date object (March 31, 2026)
@@ -337,6 +486,12 @@ parseDate("2026.03.31");
 parseDate("2026-03-31T15:30:00Z");
 // → Date object (March 31, 2026, 3:30 PM UTC)
 
+parseDate("31 Mar 26", { strict: true });
+// → null
+
+parseDateDetailed("31 Mar 26", { strict: true });
+// → { success: false, reason: "strict_mismatch", ... }
+
 // `toDate()` accepts the same Gregorian string forms as `parseDate()`,
 // plus `Date` objects and timestamps.
 // Supported string shapes:
@@ -352,6 +507,26 @@ parseDate("2026-03-31T15:30:00Z");
 // - Common Bangla month aliases like `Boishakh`, `Poush`, `Falgun`, `Asharh`
 ```
 
+### Global Defaults
+
+```ts
+import { format, getDefaults, setDefaults } from "@coreify/tarikh";
+
+setDefaults({
+  locale: "bn-BD",
+  mode: "standard",
+  month: "long",
+  timeZone: "UTC",
+  hijriSystem: "islamic-civil"
+});
+
+getDefaults();
+// → { locale: "bn-BD", mode: "standard", month: "long", timeZone: "UTC", hijriSystem: "islamic-civil" }
+
+format("2026-03-31");
+// → Uses the configured defaults
+```
+
 ### Utilities
 
 ```ts
@@ -406,53 +581,86 @@ import {
 
 ## 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            |
 
-Primary React API:
-
-Use `Tarikh` for the default formatter, then reach for the nested variants when you want relative time or Bangla calendar rendering.
+> Import from `@coreify/tarikh/react` only when you need the React components.
 
 ```tsx
 import { Tarikh } from "@coreify/tarikh/react";
 
-<Tarikh value={new Date()} />
-<Tarikh.Relative value={new Date()} />
-<Tarikh.Bangla value={new Date()} locale="bn-BD" />
+const date = "2026-03-31";
+
+<Tarikh value={date} />
+<Tarikh.Relative value={date} />
+<Tarikh.Bangla value={date} locale="bn-BD" />
+<Tarikh.Hijri value={date} locale="bn-BD" />
+<Tarikh.Relative value={date} relativeStyle="short" />
 ```
 
 ```bash
 npm install @coreify/tarikh react
 ```
 
-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.
-
-`Tarikh` handles standard date formatting, `Tarikh.Relative` handles relative time, and `Tarikh.Bangla` handles Bangla calendar output.
+| 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 |
+| Relative prop note | Use `relativeStyle` instead of `style` on `Tarikh.Relative` to avoid colliding with the native DOM `style` prop               |
 
 ## What `Intl.DateTimeFormat` cannot do
 
-If you're building for Bangladesh, existing libraries are not enough.
+| 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             |
 
-## TypeScript
+## Common Pitfalls
 
-Fully typed with strict mode. Start with the primary types below; the package also exports the lower-level calendar and helper types for advanced use.
+| Pitfall                        | What to watch for                                                                                           |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| Hijri mismatch                 | Tarikh uses `Intl` and defaults to `islamic-umalqura`; local moon-sighting calendars may differ             |
+| Time zone expectations         | Hijri conversion changes with `timeZone`, so `Asia/Dhaka` and `UTC` can return different days               |
+| `short` vs `long` month output | Standard mode defaults to short English month names but long Bangla month names unless you override `month` |
+| Strict parsing                 | `strict: true` rejects loose helpers like two-digit years and legacy Bangla month aliases                   |
+
+## TypeScript
 
-Type-level contract note: when using `pattern`, `mode` is intentionally disallowed in TypeScript.
+| Type                             | Purpose                                                                |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| `FormatOptions`                  | Primary object-based formatting contract                               |
+| `BanglaCalendarResult<TLocale>`  | Locale-aware structured Bangla calendar return type                    |
+| `HijriCalendarResult<TLocale>`   | Locale-aware structured Hijri return type                              |
+| `BanglaCalendarOptions<TLocale>` | Locale-aware structured Bangla conversion options                      |
+| `HijriCalendarOptions<TLocale>`  | Locale-aware structured Hijri conversion options                       |
+| `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 {
+  BanglaCalendarOptions,
+  BanglaCalendarResult,
   Locale,
   FormatMode,
   FormatOptions,
   DateInput,
+  HijriCalendarOptions,
+  HijriCalendarResult,
   RelativeTimeOptions
 } from "@coreify/tarikh";