@rushdi94/hijri-datepicker 1.0.1

package/README.md

@@ -0,0 +1,212 @@
+# @rushdi94/hijri-datepicker
+
+A fully customizable **Hijri (Islamic) date picker** component.
+
+- No framework required — works in React, Angular, Vue, or plain HTML
+- Pure Hijri calendar (Tabular Islamic Calendar algorithm)
+- RTL **and** LTR layout support
+- Fully customizable colors via simple options
+- TypeScript types included
+- Zero runtime dependencies
+
+---
+
+## Installation
+
+```bash
+npm install @rushdi94/hijri-datepicker
+```
+
+---
+
+## Quick Start
+
+```html
+<div id="my-picker"></div>
+```
+
+```js
+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"
+  },
+});
+```
+
+---
+
+## Custom Colors
+
+```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',
+});
+```
+
+---
+
+## RTL & LTR Support
+
+**RTL (Arabic / Urdu / Persian) — default:**
+```js
+new HijriDatePicker({
+  container: '#picker',
+  dir: 'rtl',  // default, Arabic labels
+});
+```
+
+**LTR (English / European interfaces):**
+```js
+new HijriDatePicker({
+  container: '#picker',
+  dir: 'ltr',
+  primaryColor: '#1565c0',
+  weekdayLabels: ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'],
+  monthLabels: [
+    'Muharram','Safar',"Rabi' I","Rabi' II",
+    'Jumada I','Jumada II','Rajab',"Sha'ban",
+    'Ramadan','Shawwal',"Dhu al-Qi'dah","Dhu al-Hijjah",
+  ],
+});
+```
+
+---
+
+## Inline Mode
+
+```js
+new HijriDatePicker({
+  container: '#calendar-area',
+  inline: true,        // always visible, no input field
+  primaryColor: '#2e7d32',
+});
+```
+
+---
+
+## All Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `container` | `string \| HTMLElement` | **required** | CSS selector or DOM element |
+| `dir` | `'rtl' \| 'ltr'` | `'rtl'` | Layout direction |
+| `inline` | `boolean` | `false` | Show calendar without an input |
+| `placeholder` | `string` | Arabic text | Input placeholder |
+| `primaryColor` | `string` | `'#8b1a2e'` | Main color (header, selected, today) |
+| `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`) |
+| `weekdayLabels` | `string[7]` | Arabic | Column headers Sun→Sat |
+| `monthLabels` | `string[12]` | Arabic | Muharram→Dhu al-Hijjah |
+| `editable` | `boolean` | `false` | Allow typing in the input |
+| `initialDate` | `HijriDate` | today | Initial calendar view |
+| `onSelect` | `(date, fmt) => void` | — | Date selection callback |
+| `onOpen` | `() => void` | — | Called when picker opens |
+| `onClose` | `() => void` | — | Called when picker closes |
+
+---
+
+## 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
+```
+
+---
+
+## Helper Functions
+
+```js
+import { toHijri, toGregorian, formatHijri, todayHijri } from '@rushdi94/hijri-datepicker';
+
+toHijri(new Date('2026-05-17'))
+// → { year: 1447, month: 11, day: 30 }
+
+toGregorian(1447, 9, 1)
+// → Date object (2026-02-28)
+
+formatHijri({ year: 1447, month: 11, day: 30 }, 'YYYY/MM/DD')
+// → "1447/11/30"
+
+todayHijri()
+// → current Hijri date
+```
+
+---
+
+## CDN / Script Tag
+
+```html
+<script src="https://unpkg.com/@rushdi94/hijri-datepicker/dist/hijri-datepicker.umd.js"></script>
+<script>
+  const { HijriDatePicker } = HijriDatePickerLib;
+  new HijriDatePicker({ container: '#el' });
+</script>
+```
+
+---
+
+## Angular
+
+```ts
+import { Component, AfterViewInit, ElementRef, ViewChild } from '@angular/core';
+import { HijriDatePicker } from '@rushdi94/hijri-datepicker';
+
+@Component({ template: `<div #picker></div>` })
+export class MyComponent implements AfterViewInit {
+  @ViewChild('picker') pickerRef!: ElementRef;
+  private hdp!: HijriDatePicker;
+
+  ngAfterViewInit() {
+    this.hdp = new HijriDatePicker({
+      container: this.pickerRef.nativeElement,
+      onSelect: (date, fmt) => console.log(date, fmt),
+    });
+  }
+  ngOnDestroy() { this.hdp.destroy(); }
+}
+```
+
+## React
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { HijriDatePicker, HijriDate } from '@rushdi94/hijri-datepicker';
+
+export function HijriPicker({ onSelect }: { onSelect: (d: HijriDate) => void }) {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const picker = new HijriDatePicker({
+      container: ref.current!,
+      onSelect: (date) => onSelect(date),
+    });
+    return () => picker.destroy();
+  }, []);
+
+  return <div ref={ref} />;
+}
+```
+
+---
+
+## License
+
+MIT