@rushdi94/hijri-datepicker 1.0.1 → 2.0.0

package/README.md

@@ -1,9 +1,11 @@
 # @rushdi94/hijri-datepicker
 
-A fully customizable **Hijri (Islamic) date picker** component.
+A fully customizable **Hijri / Gregorian DateTime Picker** — no framework required.
 
-- No framework required — works in React, Angular, Vue, or plain HTML
-- Pure Hijri calendar (Tabular Islamic Calendar algorithm)
+- **Switchable calendars** — toggle between Hijri and Gregorian in one click
+- **Time picker** — hour + minute spinners with AM/PM or 24-hour mode
+- Works in React, Angular, Vue, or plain HTML
+- Tabular Islamic Calendar algorithm — accurate & offline
 - RTL **and** LTR layout support
 - Fully customizable colors via simple options
 - TypeScript types included
@@ -30,42 +32,71 @@ import { HijriDatePicker } from '@rushdi94/hijri-datepicker';
 
 const picker = new HijriDatePicker({
   container: '#my-picker',
-  onSelect(date, formatted) {
-    console.log(date);      // { year: 1447, month: 11, day: 30 }
-    console.log(formatted); // "30/11/1447"
+  onSelect(value, formatted) {
+    console.log(value.hijri);      // { year: 1447, month: 11, day: 30 }
+    console.log(value.gregorian);  // { year: 2026, month: 5, day: 17 }
+    console.log(formatted);        // "30/11/1447"
   },
 });
 ```
 
 ---
 
-## Custom Colors
+## With Time Picker
 
 ```js
 new HijriDatePicker({
   container: '#my-picker',
-  primaryColor:   '#1565c0',  // header, selected day, today ring
-  onPrimaryColor: '#ffffff',  // text on colored surfaces
-  bodyBg:         '#f0f4ff',  // calendar background
-  dayColor:       '#1a237e',  // regular day number color
-  format:         'YYYY/MM/DD',
+  showTime: true,      // show hour / minute / AM-PM
+  use24h:   false,     // false = AM/PM (default), true = 24-hour
+  onSelect(value, formatted) {
+    console.log(value.time);   // { hour: 3, minute: 30, ampm: 'PM' }
+    console.log(formatted);    // "30/11/1447 03:30 PM"
+  },
 });
 ```
 
 ---
 
-## RTL & LTR Support
+## Start in Gregorian Mode
 
-**RTL (Arabic / Urdu / Persian) — default:**
 ```js
 new HijriDatePicker({
-  container: '#picker',
-  dir: 'rtl',  // default, Arabic labels
+  container: '#my-picker',
+  initialMode: 'gregorian',   // start showing Gregorian calendar
+  showTime: true,
+  onSelect(value, formatted) {
+    console.log(formatted);   // "17/05/2026 03:30 PM"
+  },
+});
+```
+
+The header shows a **"G"** button in Hijri mode and **"ه"** in Gregorian mode — clicking it switches the calendar while keeping the same date.
+
+---
+
+## Custom Colors
+
+```js
+new HijriDatePicker({
+  container: '#my-picker',
+  primaryColor:   '#1565c0',
+  onPrimaryColor: '#ffffff',
+  bodyBg:         '#f0f4ff',
+  dayColor:       '#1a237e',
+  format:         'YYYY/MM/DD',
 });
 ```
 
-**LTR (English / European interfaces):**
+---
+
+## RTL & LTR
+
 ```js
+// RTL (default)
+new HijriDatePicker({ container: '#picker', dir: 'rtl' });
+
+// LTR (English)
 new HijriDatePicker({
   container: '#picker',
   dir: 'ltr',
@@ -86,7 +117,7 @@ new HijriDatePicker({
 ```js
 new HijriDatePicker({
   container: '#calendar-area',
-  inline: true,        // always visible, no input field
+  inline: true,
   primaryColor: '#2e7d32',
 });
 ```
@@ -99,18 +130,22 @@ new HijriDatePicker({
 |---|---|---|---|
 | `container` | `string \| HTMLElement` | **required** | CSS selector or DOM element |
 | `dir` | `'rtl' \| 'ltr'` | `'rtl'` | Layout direction |
-| `inline` | `boolean` | `false` | Show calendar without an input |
+| `inline` | `boolean` | `false` | Always-visible calendar (no input) |
+| `initialMode` | `'hijri' \| 'gregorian'` | `'hijri'` | Starting calendar mode |
+| `showTime` | `boolean` | `false` | Show hour/minute/AM-PM spinner |
+| `use24h` | `boolean` | `false` | 24-hour mode (no AM/PM) |
 | `placeholder` | `string` | Arabic text | Input placeholder |
-| `primaryColor` | `string` | `'#8b1a2e'` | Main color (header, selected, today) |
+| `primaryColor` | `string` | `'#8b1a2e'` | Header, selected day, today ring |
 | `onPrimaryColor` | `string` | `'#ffffff'` | Text on primary-colored surfaces |
 | `bodyBg` | `string` | `'#ffffff'` | Calendar body background |
 | `dayColor` | `string` | `'#1f2937'` | Regular day number color |
-| `format` | `string` | `'DD/MM/YYYY'` | Date format (tokens: `DD` `MM` `YYYY`) |
+| `format` | `string` | `'DD/MM/YYYY'` | Date format tokens: `DD` `MM` `YYYY` |
 | `weekdayLabels` | `string[7]` | Arabic | Column headers Sun→Sat |
-| `monthLabels` | `string[12]` | Arabic | Muharram→Dhu al-Hijjah |
+| `monthLabels` | `string[12]` | Arabic Hijri | Muharram→Dhu al-Hijjah |
+| `gregorianMonthLabels` | `string[12]` | English | January→December |
 | `editable` | `boolean` | `false` | Allow typing in the input |
-| `initialDate` | `HijriDate` | today | Initial calendar view |
-| `onSelect` | `(date, fmt) => void` | — | Date selection callback |
+| `initialDate` | `HijriDate` | today | Initial Hijri date |
+| `onSelect` | `(value, fmt) => void` | — | Selection callback |
 | `onOpen` | `() => void` | — | Called when picker opens |
 | `onClose` | `() => void` | — | Called when picker closes |
 
@@ -119,14 +154,26 @@ new HijriDatePicker({
 ## Programmatic API
 
 ```js
-picker.getValue()                            // → HijriDate | null
-picker.setValue({ year: 1447, month: 9, day: 1 })  // select a date
-picker.goTo(1447, 12)                        // navigate calendar view
-picker.clear()                               // clear selection
-picker.setColors({ primaryColor: '#e53935' }) // live color update
-picker.open()                                // open programmatically
-picker.close()                               // close programmatically
-picker.destroy()                             // remove from DOM
+picker.getValue()                               // → DateTimeValue | null
+picker.setValue({ year: 1447, month: 9, day: 1 })         // set by Hijri date
+picker.setValueGregorian({ year: 2026, month: 3, day: 1 }) // set by Gregorian
+picker.setTime(3, 30, 'PM')                     // set time
+picker.setMode('gregorian')                     // switch calendar mode
+picker.goTo(1447, 12)                           // navigate view
+picker.clear()                                  // clear selection
+picker.setColors({ primaryColor: '#e53935' })   // live color update
+picker.open() / picker.close()                  // programmatic open/close
+picker.destroy()                                // remove from DOM
+```
+
+### DateTimeValue shape
+
+```ts
+interface DateTimeValue {
+  hijri:     { year: number; month: number; day: number };
+  gregorian: { year: number; month: number; day: number };
+  time:      { hour: number; minute: number; ampm: 'AM' | 'PM' } | null;
+}
 ```
 
 ---
@@ -134,7 +181,11 @@ picker.destroy()                             // remove from DOM
 ## Helper Functions
 
 ```js
-import { toHijri, toGregorian, formatHijri, todayHijri } from '@rushdi94/hijri-datepicker';
+import {
+  toHijri, toGregorian,
+  formatHijri, formatGregorian,
+  todayHijri, todayGregorian,
+} from '@rushdi94/hijri-datepicker';
 
 toHijri(new Date('2026-05-17'))
 // → { year: 1447, month: 11, day: 30 }
@@ -145,8 +196,8 @@ toGregorian(1447, 9, 1)
 formatHijri({ year: 1447, month: 11, day: 30 }, 'YYYY/MM/DD')
 // → "1447/11/30"
 
-todayHijri()
-// → current Hijri date
+todayHijri()    // → current Hijri date
+todayGregorian() // → current Gregorian date
 ```
 
 ---
@@ -177,7 +228,8 @@ export class MyComponent implements AfterViewInit {
   ngAfterViewInit() {
     this.hdp = new HijriDatePicker({
       container: this.pickerRef.nativeElement,
-      onSelect: (date, fmt) => console.log(date, fmt),
+      showTime: true,
+      onSelect: (value, fmt) => console.log(value, fmt),
     });
   }
   ngOnDestroy() { this.hdp.destroy(); }
@@ -188,15 +240,16 @@ export class MyComponent implements AfterViewInit {
 
 ```tsx
 import { useEffect, useRef } from 'react';
-import { HijriDatePicker, HijriDate } from '@rushdi94/hijri-datepicker';
+import { HijriDatePicker, DateTimeValue } from '@rushdi94/hijri-datepicker';
 
-export function HijriPicker({ onSelect }: { onSelect: (d: HijriDate) => void }) {
+export function HijriPicker({ onSelect }: { onSelect: (d: DateTimeValue) => void }) {
   const ref = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
     const picker = new HijriDatePicker({
       container: ref.current!,
-      onSelect: (date) => onSelect(date),
+      showTime: true,
+      onSelect: (value) => onSelect(value),
     });
     return () => picker.destroy();
   }, []);
@@ -207,6 +260,20 @@ export function HijriPicker({ onSelect }: { onSelect: (d: HijriDate) => void })
 
 ---
 
+## Changelog
+
+### v2.0.0
+- **Gregorian calendar mode** — toggle between Hijri and Gregorian in the header
+- **Time picker** — hour/minute spinners with AM/PM or 24-hour mode
+- `onSelect` now receives `DateTimeValue` (includes both Hijri + Gregorian + time)
+- New options: `initialMode`, `showTime`, `use24h`, `gregorianMonthLabels`
+- New API: `setValueGregorian()`, `setTime()`, `setMode()`
+
+### v1.0.1
+- Initial public release — Hijri-only date picker
+
+---
+
 ## License
 
 MIT