Calendar

\r\n

\r\n \r\n \r\n

\r\n

\r\n\r\n \r\n \r\n\r\n```\r\n\r\n## Configuration\r\n\r\nThe calendar is configured through `src/config.js`. Here are the available options:\r\n\r\n### Language\r\n\r\n```javascript\r\nexport const LANG = \"ar\"; // \"ar\" for Arabic, \"en\" for English\r\n```\r\n\r\n### Hijri Calendar System\r\n\r\n```javascript\r\nexport const HIJRI_SYSTEM = \"ummalqura\";\r\n// Options:\r\n// - \"ummalqura\" (default): Umm Al-Qura calculations (most widely used in Saudi Arabia and Gulf states)\r\n// - \"islamic-civil\": Islamic Civil calendar system\r\n//\r\n// Note: Uses native Intl.DateTimeFormat API - browser support for Islamic calendars:\r\n// - Modern browsers (Chrome 85+, Firefox 93+, Safari 15+)\r\n// - Mobile browsers fully supported\r\n// - No additional libraries needed!\r\n//\r\n// Technical: The converter automatically handles Arabic numeral conversion (٠-٩ → 0-9)\r\n// This ensures correct date calculations regardless of locale\r\n```\r\n\r\n### Colors\r\n\r\n```javascript\r\nexport const GREGORIAN_COLOR = \"#444\"; // Gregorian date color\r\nexport const HIJRI_COLOR = \"#2F6F4E\"; // Hijri date color\r\nexport const TODAY_BG = \"#DEB758\"; // Today's date background\r\n```\r\n\r\n### Holidays Display\r\n\r\n```javascript\r\nexport const SHOW_CARRY_OVER_HOLIDAYS = true; // Show holidays from adjacent months\r\n```\r\n\r\n### Holiday Definitions\r\n\r\nAdd holidays to the `HOLIDAYS` array:\r\n\r\n```javascript\r\nexport const HOLIDAYS = [\r\n {\r\n name: { ar: \"عيد الفطر\", en: \"Eid Al-Fitr\" },\r\n start: \"2026-03-14\",\r\n end: \"2026-03-25\",\r\n color: \"#cd9364\",\r\n },\r\n {\r\n name: { ar: \"عيد الأضحى\", en: \"Eid Al-Adha\" },\r\n start: \"2026-05-23\",\r\n end: \"2026-05-31\",\r\n color: \"#cd9364\",\r\n },\r\n];\r\n```\r\n\r\n## API\r\n\r\n### Functions\r\n\r\n#### `renderCalendar(date)`\r\n\r\nRenders the calendar for a specific date. Called automatically on month navigation.\r\n\r\n```javascript\r\nimport { renderCalendar } from \"./calendar.js\";\r\n\r\nconst date = new Date(2026, 0, 1);\r\nrenderCalendar(date);\r\n```\r\n\r\n### Hijri Date Utilities (Zero Dependencies)\r\n\r\nThe `hijriConverter.js` module provides utility functions for working with Hijri dates using native browser APIs:\r\n\r\n```javascript\r\nimport {\r\n getHijriDate,\r\n getHijriMonthName,\r\n getHijriYear,\r\n getHijriDay,\r\n formatHijriDate,\r\n} from \"./date/hijriConverter.js\";\r\n\r\n// Get full Hijri date object\r\nconst hijri = getHijriDate(new Date());\r\n// { year: 1447, month: 6, day: 15 }\r\n\r\n// Get Hijri month name\r\nconst monthName = getHijriMonthName(new Date(), \"ar\");\r\n// \"جمادى الآخرة\"\r\n\r\n// Get individual components\r\nconst year = getHijriYear(new Date()); // 1447\r\nconst day = getHijriDay(new Date()); // 15\r\n\r\n// Format complete Hijri date\r\nconst formatted = formatHijriDate(new Date(), \"ar\");\r\n// {\r\n// day: 15,\r\n// month: 6,\r\n// monthName: \"جمادى الآخرة\",\r\n// year: 1447,\r\n// formatted: \"15/6/1447\"\r\n// }\r\n```\r\n\r\n**No imports needed for the calendar itself** - it handles date conversion internally!\r\n\r\n### Navigation\r\n\r\nThe calendar includes built-in navigation:\r\n\r\n- **Buttons**: Click \"Previous\" and \"Next\" buttons\r\n- **Keyboard**: Use Left/Right arrow keys\r\n\r\n```html\r\n \r\n```\r\n\r\n## File Structure\r\n\r\n```\r\nsrc/\r\n├── calendar.js # Main calendar component\r\n├── calendar.css # Styles\r\n├── config.js # Configuration & holidays\r\n├── index.js # Backward compatibility\r\n└── date/\r\n ├── getHolidayForDate.js\r\n ├── isHolidayVisibleInMonth.js\r\n ├── isCarryOverHoliday.js\r\n ├── isRangeOverlapping.js\r\n ├── normalizeDate.js\r\n └── getUmmAlQuraDate.js\r\n```\r\n\r\n## Accessibility\r\n\r\n- ✓ Full keyboard navigation (Arrow Left/Right for month navigation)\r\n- ✓ ARIA labels on all calendar cells\r\n- ✓ Automatic RTL (Right-to-Left) support for Arabic\r\n- ✓ High contrast design suitable for screen readers\r\n- ✓ Focus indicators on interactive elements\r\n\r\n## Customization\r\n\r\n### Custom Styling\r\n\r\nOverride CSS variables or classes:\r\n\r\n```css\r\n.calendar-container {\r\n width: 500px; /* Make it wider */\r\n}\r\n\r\n.day-cell .date-content {\r\n border-radius: 8px; /* Add rounded corners */\r\n}\r\n```\r\n\r\n### Custom Colors\r\n\r\nEdit `src/config.js`:\r\n\r\n```javascript\r\nexport const GREGORIAN_COLOR = \"#3498db\";\r\nexport const HIJRI_COLOR = \"#e74c3c\";\r\nexport const TODAY_BG = \"#f39c12\";\r\n```\r\n\r\n### Add More Holidays\r\n\r\n```javascript\r\nexport const HOLIDAYS = [\r\n // ... existing holidays\r\n {\r\n name: { ar: \"اليوم الوطني\", en: \"National Day\" },\r\n start: \"2026-09-23\",\r\n end: \"2026-09-23\",\r\n color: \"#27ae60\",\r\n },\r\n];\r\n```\r\n\r\n## Browser Support\r\n\r\nFor Hijri calendar (Islamic calendar) support:\r\n\r\n- **Chrome/Edge**: 85+ (full Intl.DateTimeFormat Islamic support)\r\n- **Firefox**: 93+\r\n- **Safari**: 15+\r\n- **Mobile browsers**: Fully supported (iOS Safari 15+, Chrome Mobile 85+)\r\n\r\nFor basic calendar functionality:\r\n\r\n- All modern browsers with ES6 support\r\n\r\nUses native `Intl.DateTimeFormat` with zero external dependencies!\r\n\r\n## Dependencies\r\n\r\n**Zero runtime dependencies!** This package uses only native browser APIs.\r\n\r\n- No npm packages required\r\n- Uses `Intl.DateTimeFormat` with Islamic calendar support\r\n- Significantly smaller bundle size\r\n\r\n## Optional: Advanced Hijri Calculations\r\n\r\nIf you need additional Islamic calendar systems (Astronomical, Saudi Umm Al-Qura alternatives, etc.), you can optionally use:\r\n\r\n```bash\r\nnpm install hijri-converter # For advanced conversions\r\n```\r\n\r\nBut it's not required for basic usage - the default Umm Al-Qura (via Intl API) works great for most cases!\r\n\r\n## Development\r\n\r\n```bash\r\n# Install dev dependencies (Vite for bundling)\r\nnpm install\r\n\r\n# Start development server\r\nnpm run dev\r\n\r\n# Build for production\r\nnpm run build\r\n```\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n## Changelog\r\n\r\n### Version 1.0.0\r\n\r\n- Initial release\r\n- Dual calendar display\r\n- Multilingual support\r\n- Holiday management\r\n- Accessibility improvements\r\n- RTL support\r\n- Keyboard navigation\r\n","readmeFilename":"README.md","_rev":"1-656b912cc3d123b03751a05566199ca2"}