From 988c60a7e97c1d1040c073db8bca99072afaa6b2 Mon Sep 17 00:00:00 2001 From: Aric Camarata Date: Fri, 29 May 2026 06:34:20 -0400 Subject: [PATCH] chore: polish pubspec, add wiki docs and CHANGELOG --- .claude/AGENTS.md | 1 - .github/wiki/Home.md | 34 +++++++++++----- .github/wiki/examples/basic-usage.md | 53 ++++++++++++++++++++++++ .github/wiki/guides/advanced.md | 49 ++++++++++++++++++++++ .github/wiki/guides/quickstart.md | 61 ++++++++++++++++++++++++++++ CHANGELOG.md | 20 +++++++++ pubspec.yaml | 2 + 7 files changed, 209 insertions(+), 11 deletions(-) delete mode 120000 .claude/AGENTS.md create mode 100644 .github/wiki/examples/basic-usage.md create mode 100644 .github/wiki/guides/advanced.md create mode 100644 .github/wiki/guides/quickstart.md create mode 100644 CHANGELOG.md diff --git a/.claude/AGENTS.md b/.claude/AGENTS.md deleted file mode 120000 index 681311e..0000000 --- a/.claude/AGENTS.md +++ /dev/null @@ -1 +0,0 @@ -CLAUDE.md \ No newline at end of file diff --git a/.github/wiki/Home.md b/.github/wiki/Home.md index 604e577..c6dffbd 100644 --- a/.github/wiki/Home.md +++ b/.github/wiki/Home.md @@ -1,20 +1,34 @@ # pray_calc_dart -Islamic prayer times for Dart and Flutter. Implements the MCW seasonal model and dynamic twilight angles. Uses [nrel_spa](https://pub.dev/packages/nrel_spa) for the NREL Solar Position Algorithm. +Islamic prayer times for Dart and Flutter. Calculates Fajr, Dhuhr, Asr, Maghrib, Isha, midnight, and Qiyam for any date and location. Implements the MCW seasonal model and Dynamic Prayer Calculation (DPC) algorithm. Depends on `nrel_spa` for solar positioning. -## Quick Start +## Install + +```yaml +dependencies: + pray_calc_dart: ^1.0.0 +``` ```dart import 'package:pray_calc_dart/pray_calc_dart.dart'; -final times = getTimes(DateTime(2024, 3, 15), 40.7128, -74.0060, -5.0); -print('Fajr: ${formatTime(times.fajr)}'); -print('Dhuhr: ${formatTime(times.dhuhr)}'); -print('Maghrib: ${formatTime(times.maghrib)}'); -print('Isha: ${formatTime(times.isha)}'); +final times = getTimes( + DateTime.utc(2024, 3, 15), + 21.3891, // Makkah latitude + 39.8579, // longitude + 3.0, // UTC offset (AST) +); + +print('Fajr: ${times.fajr.toStringAsFixed(4)} h'); +print('Dhuhr: ${times.dhuhr.toStringAsFixed(4)} h'); +print('Maghrib: ${times.maghrib.toStringAsFixed(4)} h'); +print('Isha: ${times.isha.toStringAsFixed(4)} h'); ``` -## Pages +## Contents -- [API Reference](API-Reference): Full function and type reference -- [Dynamic Angle Algorithm](Dynamic-Algorithm): Physics-grounded twilight angle computation +- [Quickstart Guide](guides/quickstart) — install, first call, config options +- [Advanced Usage](guides/advanced) — madhab, custom angles, seasonal model +- [API Reference](API-Reference) — full function and type reference +- [Examples](examples/basic-usage) — real-world snippets +- [Contributing](CONTRIBUTING) diff --git a/.github/wiki/examples/basic-usage.md b/.github/wiki/examples/basic-usage.md new file mode 100644 index 0000000..34c2ce4 --- /dev/null +++ b/.github/wiki/examples/basic-usage.md @@ -0,0 +1,53 @@ +# Basic Usage Examples + +## Daily Prayer Times for Multiple Cities + +```dart +import 'package:pray_calc_dart/pray_calc_dart.dart'; + +void printPrayers(String city, double lat, double lng, double utcOffset) { + final times = getTimes(DateTime.utc(2024, 3, 15), lat, lng, utcOffset); + + String fmt(double h) { + if (h.isNaN) return '--:--'; + final hh = h.truncate(); + final mm = ((h - hh) * 60).round(); + return '${hh.toString().padLeft(2, '0')}:${mm.toString().padLeft(2, '0')}'; + } + + print('$city'); + print(' Fajr: ${fmt(times.fajr)}'); + print(' Dhuhr: ${fmt(times.dhuhr)}'); + print(' Asr: ${fmt(times.asr)}'); + print(' Maghrib: ${fmt(times.maghrib)}'); + print(' Isha: ${fmt(times.isha)}'); +} + +void main() { + printPrayers('Makkah', 21.3891, 39.8579, 3.0); + printPrayers('Istanbul', 41.0082, 28.9784, 3.0); + printPrayers('London', 51.5074, -0.1278, 0.0); + printPrayers('New York', 40.7128, -74.0060, -5.0); +} +``` + +## Monthly Calendar + +```dart +import 'package:pray_calc_dart/pray_calc_dart.dart'; + +void main() { + const lat = 40.7128; + const lng = -74.0060; + const utcOffset = -5.0; + + print('Date,Fajr,Dhuhr,Asr,Maghrib,Isha'); + for (int day = 1; day <= 30; day++) { + final date = DateTime.utc(2024, 3, day); + final t = getTimes(date, lat, lng, utcOffset); + + String h(double v) => v.toStringAsFixed(4); + print('2024-03-${day.toString().padLeft(2, "0")},${h(t.fajr)},${h(t.dhuhr)},${h(t.asr)},${h(t.maghrib)},${h(t.isha)}'); + } +} +``` diff --git a/.github/wiki/guides/advanced.md b/.github/wiki/guides/advanced.md new file mode 100644 index 0000000..d3788af --- /dev/null +++ b/.github/wiki/guides/advanced.md @@ -0,0 +1,49 @@ +# Advanced Usage + +## Madhab Selection + +The Asr time differs between the Hanafi and standard (Shafi'i/Maliki/Hanbali) methods: + +```dart +import 'package:pray_calc_dart/pray_calc_dart.dart'; + +final standard = getTimes( + DateTime.utc(2024, 3, 15), + 40.7128, -74.0060, -5.0, + config: const PrayerConfig(madhab: Madhab.standard), +); + +final hanafi = getTimes( + DateTime.utc(2024, 3, 15), + 40.7128, -74.0060, -5.0, + config: const PrayerConfig(madhab: Madhab.hanafi), +); + +print('Asr (standard): ${standard.asr.toStringAsFixed(4)} h'); +print('Asr (Hanafi): ${hanafi.asr.toStringAsFixed(4)} h'); +``` + +## MCW Seasonal Model + +The MCW (Mohammed Camille Widad) seasonal model adjusts Fajr and Isha depression angles across the year to match observed sighting data. This is the default behavior. The DPC (Dynamic Prayer Calculation) variant uses ML-calibrated angles derived from verified sighting observations. + +Both models are used automatically based on latitude and date. No configuration is needed. + +## Fixed Angle Override + +For interoperability with fixed-angle calculation methods (ISNA, MWL, etc.): + +```dart +final times = getTimes( + DateTime.utc(2024, 3, 15), + 40.7128, -74.0060, -5.0, + config: const PrayerConfig( + fajrAngle: 15.0, // ISNA + ishaAngle: 15.0, + ), +); +``` + +## High Latitude Adjustments + +At latitudes above 48°N or below 48°S, Fajr and Isha times may behave unusually due to near-continuous twilight. The library applies the Middle of Night method automatically for extreme latitudes. Check `times.fajr.isNaN` to detect fallback conditions. diff --git a/.github/wiki/guides/quickstart.md b/.github/wiki/guides/quickstart.md new file mode 100644 index 0000000..0646b2d --- /dev/null +++ b/.github/wiki/guides/quickstart.md @@ -0,0 +1,61 @@ +# Quickstart + +## Install + +Add to `pubspec.yaml`: + +```yaml +dependencies: + pray_calc_dart: ^1.0.0 +``` + +Run `dart pub get`. + +## First Call + +```dart +import 'package:pray_calc_dart/pray_calc_dart.dart'; + +void main() { + final times = getTimes( + DateTime.utc(2024, 3, 15), + 21.3891, // Makkah latitude + 39.8579, // longitude + 3.0, // UTC offset (Arabia Standard Time) + ); + + print('Fajr: ${times.fajr.toStringAsFixed(4)} h'); + print('Dhuhr: ${times.dhuhr.toStringAsFixed(4)} h'); + print('Asr: ${times.asr.toStringAsFixed(4)} h'); + print('Maghrib: ${times.maghrib.toStringAsFixed(4)} h'); + print('Isha: ${times.isha.toStringAsFixed(4)} h'); +} +``` + +## Output Fields + +`getTimes` returns a `PrayerTimes` object: + +| Field | Type | Description | +| --- | --- | --- | +| `fajr` | `double` | Fajr time (decimal hours, local) | +| `dhuhr` | `double` | Dhuhr time | +| `asr` | `double` | Asr time | +| `maghrib` | `double` | Maghrib time (sunset) | +| `isha` | `double` | Isha time | +| `midnight` | `double` | Islamic midnight | +| `qiyam` | `double` | Last third of night start | + +All times are decimal hours in the local timezone defined by `utcOffset`. + +## Converting to DateTime + +```dart +DateTime timeToDateTime(DateTime date, double hours, double utcOffset) { + final totalMinutes = (hours * 60).round(); + final h = totalMinutes ~/ 60; + final m = totalMinutes % 60; + return DateTime(date.year, date.month, date.day, h, m) + .subtract(Duration(hours: utcOffset.truncate(), minutes: ((utcOffset % 1) * 60).round())); +} +``` diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..1bd2f06 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,20 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). +This project adheres to [Semantic Versioning](https://semver.org/). + +## [1.0.0] - 2026-05-25 + +### Added + +- Initial public release. +- `getTimes` — calculates Fajr, Dhuhr, Asr, Maghrib, Isha, midnight, and Qiyam times for any date and location. +- MCW seasonal model for Fajr and Isha twilight angles. +- Dynamic Prayer Calculation (DPC) algorithm with ML-calibrated depression angles. +- `PrayerConfig` — configurable madhab (Hanafi/standard Asr), calculation method, and UTC offset. +- Pure Dart implementation. Zero runtime dependencies beyond `nrel_spa`. +- Depends on `nrel_spa ^1.0.0` for NREL Solar Position Algorithm. +- Dart SDK `^3.7.0` compatibility. +- 24 unit tests covering all 7 prayer outputs across known locations and dates. diff --git a/pubspec.yaml b/pubspec.yaml index 01c55d6..1727246 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -4,8 +4,10 @@ description: > library implementing the MCW seasonal model and dynamic twilight angles. Uses nrel_spa for the NREL Solar Position Algorithm. version: 1.0.0 +homepage: https://github.com/acamarata/pray-calc-dart repository: https://github.com/acamarata/pray-calc-dart issue_tracker: https://github.com/acamarata/pray-calc-dart/issues +publisher: ariccamarata.com topics: - prayer-times - islamic