From 51894b95a05bfc422d195363a38f736b04f1d44f Mon Sep 17 00:00:00 2001 From: Aric Camarata Date: Fri, 29 May 2026 06:34:29 -0400 Subject: [PATCH] chore: polish pubspec, add wiki docs --- .claude/AGENTS.md | 1 - .github/wiki/Home.md | 24 ++++++++----- .github/wiki/examples/basic-usage.md | 45 +++++++++++++++++++++++++ .github/wiki/guides/advanced.md | 50 ++++++++++++++++++++++++++++ .github/wiki/guides/quickstart.md | 50 ++++++++++++++++++++++++++++ pubspec.yaml | 2 ++ 6 files changed, 163 insertions(+), 9 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 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 a2eddda..7ac52d3 100644 --- a/.github/wiki/Home.md +++ b/.github/wiki/Home.md @@ -1,21 +1,29 @@ # qibla -Qibla direction, great-circle path, and haversine distance for Dart and Flutter. Pure math, zero dependencies. +Qibla direction, great-circle path, and haversine distance for Dart and Flutter. Computes the bearing to the Ka'bah from any point on Earth. Pure math, zero dependencies. -## Quick Start +## Install + +```yaml +dependencies: + qibla: ^1.0.1 +``` ```dart import 'package:qibla/qibla.dart'; final bearing = qiblaAngle(40.7128, -74.006); -print(bearing); // ~58.48 -print(compassDir(bearing)); // NE +print(bearing); // ~58.48 +print(compassDir(bearing)); // NE final km = distanceKm(40.7128, -74.006, kaabaLat, kaabaLng); -print(km); // ~9634 +print(km); // ~9634 ``` -## Pages +## Contents -- [API Reference](API-Reference): Full function and constant reference -- [Architecture](Architecture): Spherical trigonometry and Slerp implementation +- [Quickstart Guide](guides/quickstart) — install, first call, compass directions +- [Advanced Usage](guides/advanced) — great-circle paths, custom interpolation +- [API Reference](API-Reference) — full function and constant 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..e8430d8 --- /dev/null +++ b/.github/wiki/examples/basic-usage.md @@ -0,0 +1,45 @@ +# Basic Usage Examples + +## Qibla for Multiple Cities + +```dart +import 'package:qibla/qibla.dart'; + +void main() { + final cities = [ + ('New York', 40.7128, -74.0060), + ('London', 51.5074, -0.1278), + ('Istanbul', 41.0082, 28.9784), + ('Jakarta', -6.2088, 106.8456), + ('Cape Town', -33.9249, 18.4241), + ]; + + print('City Bearing Direction Distance'); + print('${'─' * 54}'); + + for (final (city, lat, lng) in cities) { + final bearing = qiblaAngle(lat, lng); + final dir = compassDir(bearing); + final km = distanceKm(lat, lng, kaabaLat, kaabaLng); + + print('${city.padRight(18)}${bearing.toStringAsFixed(1).padLeft(6)}° ${dir.padRight(9)} ${km.toStringAsFixed(0)} km'); + } +} +``` + +## Great-Circle Path Waypoints + +```dart +import 'package:qibla/qibla.dart'; + +void main() { + // 8 waypoints from London to Makkah + final path = greatCirclePath(51.5074, -0.1278, kaabaLat, kaabaLng, 8); + + print('Waypoints from London to Makkah:'); + for (int i = 0; i < path.length; i++) { + final p = path[i]; + print(' ${i + 1}. ${p.latitude.toStringAsFixed(4)}°, ${p.longitude.toStringAsFixed(4)}°'); + } +} +``` diff --git a/.github/wiki/guides/advanced.md b/.github/wiki/guides/advanced.md new file mode 100644 index 0000000..b493b37 --- /dev/null +++ b/.github/wiki/guides/advanced.md @@ -0,0 +1,50 @@ +# Advanced Usage + +## Great-Circle Path + +Compute N interpolated waypoints along the great-circle route from your location to the Ka'bah: + +```dart +import 'package:qibla/qibla.dart'; + +void main() { + // 5 waypoints from New York to Makkah + final path = greatCirclePath(40.7128, -74.0060, kaabaLat, kaabaLng, 5); + + for (final point in path) { + print('${point.latitude.toStringAsFixed(4)}, ${point.longitude.toStringAsFixed(4)}'); + } +} +``` + +The path uses spherical linear interpolation (Slerp) and returns `n` evenly spaced coordinates including the start and end points. + +## Custom Destination + +`distanceKm` and `greatCirclePath` work with any two points, not just the Ka'bah: + +```dart +// Distance between two mosques +final km = distanceKm(51.5074, -0.1278, 40.7128, -74.0060); +print('London to New York: ${km.toStringAsFixed(0)} km'); + +// Path from Istanbul to Makkah +final path = greatCirclePath(41.0082, 28.9784, kaabaLat, kaabaLng, 10); +``` + +## Flutter Compass Widget Integration + +```dart +import 'package:qibla/qibla.dart'; + +// In a StatefulWidget with device compass heading: +Widget buildQiblaArrow(double deviceHeading, double lat, double lng) { + final qibla = qiblaAngle(lat, lng); + final arrowRotation = (qibla - deviceHeading) * (pi / 180); + + return Transform.rotate( + angle: arrowRotation, + child: const Icon(Icons.navigation, size: 48), + ); +} +``` diff --git a/.github/wiki/guides/quickstart.md b/.github/wiki/guides/quickstart.md new file mode 100644 index 0000000..93ddcbd --- /dev/null +++ b/.github/wiki/guides/quickstart.md @@ -0,0 +1,50 @@ +# Quickstart + +## Install + +Add to `pubspec.yaml`: + +```yaml +dependencies: + qibla: ^1.0.1 +``` + +Run `dart pub get`. + +## Qibla Bearing + +```dart +import 'package:qibla/qibla.dart'; + +void main() { + // New York + final bearing = qiblaAngle(40.7128, -74.0060); + print('Bearing to Ka''bah: ${bearing.toStringAsFixed(2)}°'); + print('Compass direction: ${compassDir(bearing)}'); + print('Full direction: ${compassPoint(bearing)}'); + + // Distance to Ka'bah + final km = distanceKm(40.7128, -74.0060, kaabaLat, kaabaLng); + print('Distance: ${km.toStringAsFixed(0)} km'); +} +``` + +## Compass Directions + +`compassDir` returns an 8-point abbreviation (N, NE, E, SE, S, SW, W, NW). +`compassPoint` returns the full name (North, Northeast, East, etc.). + +```dart +final bearing = qiblaAngle(lat, lng); +final short = compassDir(bearing); // "NE" +final full = compassPoint(bearing); // "Northeast" +``` + +## Ka'bah Coordinates + +The Ka'bah coordinates are exported as constants: + +```dart +print(kaabaLat); // 21.4225 +print(kaabaLng); // 39.8262 +``` diff --git a/pubspec.yaml b/pubspec.yaml index 6fbecca..a8fe07a 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -4,8 +4,10 @@ description: > Flutter. Pure math, zero dependencies. Computes bearing to the Ka'bah from any point on Earth. version: 1.0.1 +homepage: https://github.com/acamarata/qibla-dart repository: https://github.com/acamarata/qibla-dart issue_tracker: https://github.com/acamarata/qibla-dart/issues +publisher: ariccamarata.com topics: - qibla - islamic