Hijri Mobile Widget

A minimal Hijri (Islamic) calendar home-screen widget for iOS and Android, plus a tiny companion app screen. The widget shows the day number inside a black circle; tapping opens the app, where the full Hijri date (weekday, month name, year, plus Arabic) is shown below the same circle.

Hijri dates use the Umm al-Qura calendar, computed natively on each platform:

Platform	Source of truth
iOS	Calendar(identifier: .islamicUmmAlQura) (Foundation)
Android	android.icu.util.IslamicCalendar (ICU)
JS / app	Intl.DateTimeFormat('…-u-ca-islamic-umalqura')

The native widgets do not depend on JS — they keep working when the app process isn't running.

Repository layout

.
├── App.tsx, index.ts          Expo RN entry + main screen
├── src/hijri.ts               JS Hijri helpers (Intl)
├── ios-widget/                Drop into Xcode widget extension target
│   ├── HijriWidget.swift
│   ├── HijriWidgetBundle.swift
│   └── Info.plist
└── android-widget/            Drop into android/app/src/main/
    ├── HijriWidgetProvider.kt → java/com/example/hijri/widget/
    ├── res/layout/hijri_widget.xml
    ├── res/drawable/circle_bg.xml
    ├── res/xml/hijri_widget_info.xml
    └── AndroidManifest.snippet.xml

Quick start (Expo app screen)

npm install
npm start            # then press i for iOS, a for Android

This runs only the companion app — adding the home-screen widget itself requires the two wire-up steps below (because WidgetKit / AppWidget targets live outside the Expo JS bundle).

Wire up the iOS home-screen widget

1. npx expo prebuild to generate the ios/ folder.
2. Open ios/HijriWidgetApp.xcworkspace in Xcode.
3. File → New → Target → Widget Extension. Name it HijriWidget. Untick "Include Live Activity" and "Include Configuration App Intent" — not needed.
4. Delete the auto-generated .swift files in the new target, then add the files from ios-widget/ to that target (drag into Xcode, ensure target membership is only the widget extension, not the main app).
5. Replace the generated Info.plist with the one in ios-widget/Info.plist.
6. Build and run the main app once on a device/simulator, then long-press the home screen → add the Hijri widget.

Wire up the Android home-screen widget

1. npx expo prebuild to generate the android/ folder.
2. Copy android-widget/HijriWidgetProvider.kt into android/app/src/main/java/com/example/hijri/widget/ (create the widget subpackage). Adjust the package name if you changed android.package in app.json.
3. Copy:
   • res/layout/hijri_widget.xml → android/app/src/main/res/layout/
   • res/drawable/circle_bg.xml → android/app/src/main/res/drawable/
   • res/xml/hijri_widget_info.xml → android/app/src/main/res/xml/
4. Paste the <receiver> block from AndroidManifest.snippet.xml inside the <application> tag of android/app/src/main/AndroidManifest.xml.
5. npm run android. Long-press the home screen → Widgets → Hijri.

Refresh behaviour

• iOS — WidgetKit timeline; we schedule the next reload at the upcoming midnight.
• Android — updatePeriodMillis="86400000" (24 h), the minimum the system honours via AppWidgetProvider. If you need sub-day precision, schedule a WorkManager job from the provider.
• Tapping the widget on either platform launches the app; the in-app screen toggles the full date on tap of the same circle.

Contributing

Issues and pull requests are welcome. Please keep changes focused — this project deliberately stays small and dependency-light.

License

MIT © lAvArt Studio