From a5578a1def0527097c56db34dcb0e2f7e63ba6f7 Mon Sep 17 00:00:00 2001 From: Aric Camarata Date: Fri, 29 May 2026 06:34:31 -0400 Subject: [PATCH] chore: polish pubspec, add wiki docs and CHANGELOG --- .claude/AGENTS.md | 1 - .github/wiki/Home.md | 21 +++++++-- .github/wiki/examples/basic-usage.md | 61 ++++++++++++++++++++++++ .github/wiki/guides/advanced.md | 70 ++++++++++++++++++++++++++++ .github/wiki/guides/quickstart.md | 61 ++++++++++++++++++++++++ CHANGELOG.md | 29 ++++++++++++ pubspec.yaml | 2 + 7 files changed, 239 insertions(+), 6 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 4bc0eef..db731fc 100644 --- a/.github/wiki/Home.md +++ b/.github/wiki/Home.md @@ -2,7 +2,15 @@ Lunar crescent visibility for Dart and Flutter. Computes moon phase, topocentric position, illumination, and Yallop/Odeh crescent visibility criteria using Meeus algorithms. Zero dependencies. -## Quick Start +Uses Meeus lite algorithms with approximately 0.3 degree accuracy. The companion JavaScript +package (`moon-sighting` on npm) uses JPL DE442S ephemeris for sub-arcminute precision. + +## Install + +```yaml +dependencies: + moon_sighting: ^1.0.0 +``` ```dart import 'package:moon_sighting/moon_sighting.dart'; @@ -12,13 +20,16 @@ print('${phase.phaseName} (${phase.illumination.toStringAsFixed(1)}%)'); final vis = getMoonVisibilityEstimate( DateTime.utc(2025, 3, 31, 18, 30), - 21.4225, 39.8262, // Mecca + 21.4225, 39.8262, // Makkah ); print('Zone: ${vis.zone.label}'); print('Visible naked eye: ${vis.isVisibleNakedEye}'); ``` -## Pages +## Contents -- [API Reference](API-Reference): Full function and type reference -- [Visibility Criteria](Visibility-Criteria): Yallop and Odeh crescent visibility criteria +- [Quickstart Guide](guides/quickstart) — install, first call, phase and position +- [Advanced Usage](guides/advanced) — visibility criteria, new moon finding +- [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..b01d0f0 --- /dev/null +++ b/.github/wiki/examples/basic-usage.md @@ -0,0 +1,61 @@ +# Basic Usage Examples + +## Tonight's Moon + +```dart +import 'package:moon_sighting/moon_sighting.dart'; + +void main() { + final now = DateTime.now().toUtc(); + final phase = getMoonPhase(now); + final position = getMoonPosition(now, 40.7128, -74.0060); + + print('Moon tonight (New York):'); + print(' Phase: ${phase.phaseName}'); + print(' Illumination: ${phase.illumination.toStringAsFixed(1)}%'); + print(' Altitude: ${position.altitude.toStringAsFixed(2)}°'); + print(' Azimuth: ${position.azimuth.toStringAsFixed(2)}°'); + print(' Distance: ${position.distanceKm.toStringAsFixed(0)} km'); +} +``` + +## Ramadan Crescent Visibility Check + +```dart +import 'package:moon_sighting/moon_sighting.dart'; + +void main() { + // Check crescent visibility for major Muslim cities on Ramadan eve + final eveningOfCheck = DateTime.utc(2026, 2, 17, 18, 0); + + final cities = [ + ('Makkah', 21.4225, 39.8262, 3.0), + ('Istanbul', 41.0082, 28.9784, 3.0), + ('London', 51.5074, -0.1278, 0.0), + ('New York', 40.7128, -74.0060, -5.0), + ]; + + print('City Zone'); + print('${'─' * 30}'); + for (final (city, lat, lng, _) in cities) { + final vis = getMoonVisibilityEstimate(eveningOfCheck, lat, lng); + print('${city.padRight(18)}${vis.zone.label}'); + } +} +``` + +## Moon Phase Calendar + +```dart +import 'package:moon_sighting/moon_sighting.dart'; + +void main() { + print('Date,Phase,Illumination'); + for (int day = 1; day <= 30; day++) { + final date = DateTime.utc(2025, 3, day, 12, 0); + final phase = getMoonPhase(date); + print('2025-03-${day.toString().padLeft(2, "0")},' + '${phase.phaseName},${phase.illumination.toStringAsFixed(1)}%'); + } +} +``` diff --git a/.github/wiki/guides/advanced.md b/.github/wiki/guides/advanced.md new file mode 100644 index 0000000..f933cf4 --- /dev/null +++ b/.github/wiki/guides/advanced.md @@ -0,0 +1,70 @@ +# Advanced Usage + +## Yallop vs Odeh Criteria + +The package implements two published crescent visibility criteria. Both are returned in `getMoonVisibilityEstimate`: + +```dart +import 'package:moon_sighting/moon_sighting.dart'; + +final vis = getMoonVisibilityEstimate( + DateTime.utc(2025, 3, 31, 18, 30), + 21.4225, 39.8262, +); + +print('Yallop zone: ${vis.yallopZone.label}'); +print('Odeh zone: ${vis.odehZone.label}'); +print('Combined: ${vis.zone.label}'); +``` + +Yallop and Odeh zones: + +| Zone | Label | Description | +| --- | --- | --- | +| A | Easily visible | Visible to naked eye | +| B | Visible under good conditions | May be visible to naked eye | +| C | May need optical aid | Visible with binoculars | +| D | Optical aid and perfect conditions | Telescope only | +| E | Not visible | Below horizon at sunset | +| F | Below new moon | Moon sets before sun | + +## Finding the Next New Moon + +```dart +final newMoon = nearestNewMoon(DateTime.utc(2025, 3, 15)); +print('Next new moon: ${newMoon.toIso8601String()}'); +``` + +Pass `next: false` for the previous new moon: + +```dart +final prev = nearestNewMoon(DateTime.utc(2025, 3, 15), next: false); +``` + +## Monthly Crescent Calendar + +```dart +import 'package:moon_sighting/moon_sighting.dart'; + +void main() { + // Find when Ramadan crescent might be visible in 2026 + final newMoon = nearestNewMoon(DateTime.utc(2026, 3, 20)); + print('New moon: ${newMoon.toIso8601String()}'); + + // Check 3 successive evenings + for (int d = 1; d <= 3; d++) { + final check = newMoon.add(Duration(days: d, hours: 18)); + final vis = getMoonVisibilityEstimate(check, 21.4225, 39.8262); + print('Day $d: ${vis.zone.label}'); + } +} +``` + +## Accuracy and JS Comparison + +| Aspect | moon_sighting (Dart) | moon-sighting (npm/JS) | +| --- | --- | --- | +| Algorithm | Meeus Chapter 47 | JPL DE442S ephemeris | +| Position accuracy | ~0.3 degrees | Sub-arcminute | +| Bundle size | Minimal | ~500 KB (ephemeris data) | +| Best for | Flutter apps, mobile | Server-side, high precision | diff --git a/.github/wiki/guides/quickstart.md b/.github/wiki/guides/quickstart.md new file mode 100644 index 0000000..523785d --- /dev/null +++ b/.github/wiki/guides/quickstart.md @@ -0,0 +1,61 @@ +# Quickstart + +## Install + +Add to `pubspec.yaml`: + +```yaml +dependencies: + moon_sighting: ^1.0.0 +``` + +Run `dart pub get`. + +## Moon Phase + +```dart +import 'package:moon_sighting/moon_sighting.dart'; + +void main() { + final phase = getMoonPhase(); + print('Phase: ${phase.phaseName}'); + print('Illumination: ${phase.illumination.toStringAsFixed(1)}%'); +} +``` + +Pass a specific date for historical or future phases: + +```dart +final phase = getMoonPhase(DateTime.utc(2025, 3, 31)); +``` + +## Moon Position + +```dart +final position = getMoonPosition( + DateTime.utc(2025, 3, 31, 18, 30), + 21.4225, // Makkah latitude + 39.8262, // longitude +); + +print('Altitude: ${position.altitude.toStringAsFixed(2)}°'); +print('Azimuth: ${position.azimuth.toStringAsFixed(2)}°'); +print('Distance: ${position.distanceKm.toStringAsFixed(0)} km'); +``` + +## Crescent Visibility + +```dart +final vis = getMoonVisibilityEstimate( + DateTime.utc(2025, 3, 31, 18, 30), + 21.4225, 39.8262, +); + +print('Zone: ${vis.zone.label}'); +print('Visible (naked): ${vis.isVisibleNakedEye}'); +print('Visible (aided): ${vis.isVisibleWithAid}'); +``` + +## Accuracy Note + +This package uses Meeus lite algorithms with approximately 0.3 degree positional accuracy. The companion JavaScript package (`moon-sighting` on npm) uses JPL DE442S ephemeris for sub-arcminute precision. Use the JS package when observatory-grade accuracy is required. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..38aaeb9 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,29 @@ +# 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. +- `getMoonPhase` — returns moon phase name and illumination percentage for any date. +- `getMoonPosition` — computes topocentric altitude and azimuth using Meeus Chapter 47 algorithms. +- `getMoon` — combined output: phase, position, and illumination in one call. +- `getMoonVisibilityEstimate` — Yallop and Odeh crescent visibility criteria. +- `nearestNewMoon` — finds the next or previous new moon from a given date. +- `arcvMinimum` — polynomial helper for Yallop arc of vision minimum. +- `distanceKm` — lunar distance in kilometres. +- Meeus lite algorithms (Astronomical Algorithms, Jean Meeus, 2nd ed.) — no JPL ephemeris dependency. +- Pure Dart implementation. Zero runtime dependencies. +- Dart SDK `^3.7.0` compatibility. +- 64 unit tests covering all 7 SPORT features. + +### Notes + +This package uses Meeus lite algorithms with approximately 0.3 degree positional accuracy. +The companion JavaScript package (`moon-sighting` on npm) uses JPL DE442S ephemeris for +sub-arcminute precision. Use the JS package when observatory-grade accuracy is required. diff --git a/pubspec.yaml b/pubspec.yaml index b56e350..25fb933 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -4,8 +4,10 @@ description: > illumination, and Yallop/Odeh visibility criteria using Meeus algorithms. Zero dependencies. version: 1.0.0 +homepage: https://github.com/acamarata/moon-sighting-dart repository: https://github.com/acamarata/moon-sighting-dart issue_tracker: https://github.com/acamarata/moon-sighting-dart/issues +publisher: ariccamarata.com topics: - moon - lunar