docs: portfolio polish — README, wiki, API reference

2026-06-30 19:04:24 +00:00 · 2026-05-30 18:35:45 -04:00 · 2026-05-30 18:35:45 -04:00 · 0a75c4a8f8
commit 0a75c4a8f8
parent e19e4bdf20
7 changed files with 296 additions and 36 deletions
--- a/.github/wiki/API-Reference.md
+++ b/.github/wiki/API-Reference.md
@ -11,49 +11,110 @@ SpaResult getSpa(
  double elevation = 0,
  double pressure = 1013,
  double temperature = 15,
+  double deltaUt1 = 0,
  double deltaT = 67,
+  double slope = 0,
+  double azmRotation = 0,
+  double atmosRefract = 0.5667,
+  int functionCode = spaZaRts,
  List<double> customAngles = const [],
 })
 ```

-Computes solar position for a given location and moment.
+Computes solar position for a given location and moment. Returns raw fractional-hour values.
+
+Throws `ArgumentError` if any input falls outside the NREL SPA valid range.

 ### Parameters

 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
 | `date` | `DateTime` | required | UTC date and time |
-| `latitude` | `double` | required | Degrees (-90 to 90) |
-| `longitude` | `double` | required | Degrees (-180 to 180) |
-| `timezone` | `double` | required | Hours from UTC |
+| `latitude` | `double` | required | Degrees (-90 to 90, south negative) |
+| `longitude` | `double` | required | Degrees (-180 to 180, west negative) |
+| `timezone` | `double` | required | Hours from UTC (e.g., -5 for EST) |
 | `elevation` | `double` | 0 | Meters above sea level |
 | `pressure` | `double` | 1013 | Atmospheric pressure (mbar) |
 | `temperature` | `double` | 15 | Temperature (Celsius) |
+| `deltaUt1` | `double` | 0 | Difference UT1 - UTC (seconds, typically small) |
 | `deltaT` | `double` | 67 | TT - UT1 (seconds) |
-| `customAngles` | `List<double>` | [] | Zenith angles for custom rise/set computation |
+| `slope` | `double` | 0 | Surface tilt angle (degrees, for incidence) |
+| `azmRotation` | `double` | 0 | Surface azimuth rotation (degrees, for incidence) |
+| `atmosRefract` | `double` | 0.5667 | Atmospheric refraction at horizon (degrees) |
+| `functionCode` | `int` | `spaZaRts` | What to calculate; one of `spaZa`, `spaZaInc`, `spaZaRts`, `spaAll` |
+| `customAngles` | `List<double>` | `[]` | Zenith angles for custom rise/set computation |
+
+### Function codes
+
+| Constant | Value | Computes |
+| --- | --- | --- |
+| `spaZa` | 0 | Zenith and azimuth only |
+| `spaZaInc` | 1 | Zenith, azimuth, and surface incidence |
+| `spaZaRts` | 2 | Zenith, azimuth, sunrise, sunset, solar noon (default) |
+| `spaAll` | 3 | All of the above |

 ### SpaResult fields

 | Field | Type | Description |
 | --- | --- | --- |
 | `zenith` | `double` | Solar zenith angle (degrees) |
-| `azimuth` | `double` | Solar azimuth angle (degrees, clockwise from north) |
-| `sunrise` | `double` | Sunrise in fractional hours (local time) |
-| `solarNoon` | `double` | Solar noon in fractional hours (local time) |
-| `sunset` | `double` | Sunset in fractional hours (local time) |
-| `angles` | `List<SpaAngleResult>` | Rise/set pairs for each entry in `customAngles` |
+| `azimuth` | `double` | Solar azimuth angle, eastward from north (degrees) |
+| `sunrise` | `double` | Sunrise in fractional hours, local time (NaN if polar) |
+| `solarNoon` | `double` | Solar noon in fractional hours, local time (NaN if polar) |
+| `sunset` | `double` | Sunset in fractional hours, local time (NaN if polar) |
+| `incidence` | `double` | Surface incidence angle (degrees; `spaZaInc`/`spaAll` only) |
+| `angles` | `List<SpaAnglesResult>` | Rise/set pairs for each entry in `customAngles` |

-### SpaAngleResult fields
+### SpaAnglesResult fields

 | Field | Type | Description |
 | --- | --- | --- |
-| `zenith` | `double` | The requested zenith angle |
-| `sunrise` | `double` | Rise time in fractional hours for this zenith |
-| `sunset` | `double` | Set time in fractional hours for this zenith |
+| `sunrise` | `double` | Rise time in fractional hours for this zenith angle |
+| `sunset` | `double` | Set time in fractional hours for this zenith angle |

-### Custom zenith angles
+---

-Pass any solar zenith angles to get rise/set times at those angles. Standard civil/nautical/astronomical twilight angles are 96, 102, and 108 degrees respectively. Prayer time implementations use this to calculate Fajr and Isha.
+## calcSpa
+
+```dart
+SpaFormattedResult calcSpa(
+  DateTime date,
+  double latitude,
+  double longitude,
+  double timezone, {
+  // same optional parameters as getSpa
+})
+```
+
+Same as `getSpa`, but formats `sunrise`, `solarNoon`, and `sunset` as `HH:MM:SS` strings. Returns `"N/A"` for those fields during polar day or polar night.
+
+### SpaFormattedResult fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `zenith` | `double` | Solar zenith angle (degrees) |
+| `azimuth` | `double` | Solar azimuth angle (degrees) |
+| `sunrise` | `String` | Sunrise as `HH:MM:SS`, or `"N/A"` |
+| `solarNoon` | `String` | Solar noon as `HH:MM:SS`, or `"N/A"` |
+| `sunset` | `String` | Sunset as `HH:MM:SS`, or `"N/A"` |
+| `incidence` | `double` | Surface incidence angle (degrees) |
+| `angles` | `List<SpaFormattedAnglesResult>` | Rise/set pairs with formatted strings |
+
+---
+
+## formatTime
+
+```dart
+String formatTime(double hours)
+```
+
+Formats fractional hours to an `HH:MM:SS` string. Returns `"N/A"` for non-finite or negative values (polar scenarios).
+
+---
+
+## Custom zenith angles
+
+Pass any solar zenith angles to `customAngles` to get rise/set times at those depression depths. Standard angles: civil twilight = 96°, nautical = 102°, astronomical = 108°. Prayer time implementations use this for Fajr and Isha.

 ```dart
 final result = getSpa(
@ -62,8 +123,8 @@ final result = getSpa(
  customAngles: [96.0, 102.0, 108.0],
 );

-for (final angle in result.angles) {
-  print('${angle.zenith}: rise ${angle.sunrise}, set ${angle.sunset}');
+for (int i = 0; i < result.angles.length; i++) {
+  print('Angle ${i}: rise ${result.angles[i].sunrise}, set ${result.angles[i].sunset}');
 }
 ```

--- a/.github/wiki/CODE_OF_CONDUCT.md
+++ b/.github/wiki/CODE_OF_CONDUCT.md
@ -0,0 +1,32 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Accepting constructive criticism gracefully
+- Focusing on what is best for the community
+- Showing empathy toward other community members
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior. They will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project maintainer at alisalaah@gmail.com. All complaints will be reviewed and investigated. The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
--- a/.github/wiki/SECURITY.md
+++ b/.github/wiki/SECURITY.md
@ -0,0 +1,27 @@
+# Security
+
+## Scope
+
+`nrel_spa` is a pure-computation library with no network access, no file I/O, and no external dependencies. The attack surface is limited to the mathematical functions themselves.
+
+The main concern is input validation: `getSpa` and `calcSpa` throw `ArgumentError` when inputs fall outside the NREL SPA valid ranges (e.g., latitude outside -90..90, year outside -2000..6000). If you pass untrusted input to these functions, catch the error.
+
+## Reporting a Vulnerability
+
+If you discover a security issue (for example, a case where malformed input causes unexpected behavior beyond the documented `ArgumentError`), please report it privately before filing a public issue.
+
+**Contact:** alisalaah@gmail.com
+
+Include:
+
+1. A description of the vulnerability
+2. Steps to reproduce it
+3. The version of `nrel_spa` where you observed the issue
+4. Any suggested fix if you have one
+
+You can expect an acknowledgment within 48 hours and a resolution or status update within 7 days.
+
+## Known Limitations
+
+- The algorithm is valid for years -2000 to 6000 and is accurate to within ±0.0003° for solar zenith angle. Inputs outside this range produce `ArgumentError`.
+- This is a Dart port of the NREL SPA algorithm (Reda & Andreas, 2004, NREL/TP-560-34302). Numerical results match the reference implementation to the precision defined in that report.
--- a/.github/wiki/_Footer.md
+++ b/.github/wiki/_Footer.md
@ -0,0 +1,3 @@
+[![pub package](https://img.shields.io/pub/v/nrel_spa.svg)](https://pub.dev/packages/nrel_spa) &nbsp; [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/acamarata/nrel-spa-dart/blob/main/LICENSE)
+
+[pub.dev](https://pub.dev/packages/nrel_spa) | [GitHub](https://github.com/acamarata/nrel-spa-dart) | [Issues](https://github.com/acamarata/nrel-spa-dart/issues)
--- a/.github/wiki/_Sidebar.md
+++ b/.github/wiki/_Sidebar.md
@ -0,0 +1,19 @@
+## nrel_spa
+
+- [Home](Home)
+- [API Reference](API-Reference)
+
+**Guides**
+- [Quickstart](guides/quickstart)
+
+**Examples**
+- [Basic Usage](examples/basic-usage)
+- [Prayer Times Integration](examples/prayer-times-integration)
+
+**Project**
+- [Code of Conduct](CODE_OF_CONDUCT)
+- [Security](SECURITY)
+
+---
+
+[pub.dev](https://pub.dev/packages/nrel_spa) | [GitHub](https://github.com/acamarata/nrel-spa-dart)
--- a/.github/wiki/examples/prayer-times-integration.md
+++ b/.github/wiki/examples/prayer-times-integration.md
@ -0,0 +1,133 @@
+# Prayer Times Integration
+
+This example shows how to use `nrel_spa` inside a Flutter app to build a solar-position widget. It computes the current solar zenith and the times for sunrise, solar noon, and sunset, then displays them in a card.
+
+## Dependencies
+
+Add to `pubspec.yaml`:
+
+```yaml
+dependencies:
+  nrel_spa: ^1.0.0
+  geolocator: ^14.0.0
+```
+
+## SolarDayCard Widget
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:geolocator/geolocator.dart';
+import 'package:nrel_spa/nrel_spa.dart';
+
+class SolarDayCard extends StatefulWidget {
+  const SolarDayCard({super.key});
+
+  @override
+  State<SolarDayCard> createState() => _SolarDayCardState();
+}
+
+class _SolarDayCardState extends State<SolarDayCard> {
+  SpaFormattedResult? _result;
+  String? _error;
+
+  @override
+  void initState() {
+    super.initState();
+    _compute();
+  }
+
+  Future<void> _compute() async {
+    try {
+      final permission = await Geolocator.requestPermission();
+      if (permission == LocationPermission.denied ||
+          permission == LocationPermission.deniedForever) {
+        setState(() => _error = 'Location permission denied.');
+        return;
+      }
+
+      final pos = await Geolocator.getCurrentPosition();
+      final now = DateTime.now().toUtc();
+      final utcOffset = DateTime.now().timeZoneOffset.inMinutes / 60.0;
+
+      // calcSpa returns pre-formatted HH:MM:SS strings for the time fields.
+      final result = calcSpa(now, pos.latitude, pos.longitude, utcOffset);
+      setState(() => _result = result);
+    } catch (e) {
+      setState(() => _error = e.toString());
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    if (_error != null) {
+      return Card(child: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Text('Error: $_error'),
+      ));
+    }
+
+    if (_result == null) {
+      return const Card(child: Padding(
+        padding: EdgeInsets.all(16),
+        child: CircularProgressIndicator(),
+      ));
+    }
+
+    final r = _result!;
+    return Card(
+      child: Padding(
+        padding: const EdgeInsets.all(16),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Text('Solar Day', style: Theme.of(context).textTheme.titleMedium),
+            const SizedBox(height: 12),
+            _row('Sunrise', r.sunrise),
+            _row('Solar noon', r.solarNoon),
+            _row('Sunset', r.sunset),
+            _row('Zenith now', '${r.zenith.toStringAsFixed(2)}°'),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Widget _row(String label, String value) => Padding(
+    padding: const EdgeInsets.symmetric(vertical: 2),
+    child: Row(
+      mainAxisAlignment: MainAxisAlignment.spaceBetween,
+      children: [Text(label), Text(value)],
+    ),
+  );
+}
+```
+
+## Custom Zenith Angles for Twilight
+
+The `customAngles` parameter lets you request rise and set times at any zenith angle. This is useful for civil twilight (96°), nautical twilight (102°), and Islamic twilight used in prayer-time calculation (Fajr at 108°, Isha at 107°).
+
+```dart
+import 'package:nrel_spa/nrel_spa.dart';
+
+void printTwilight(double lat, double lng, double utcOffset) {
+  final date = DateTime.now().toUtc();
+
+  // spaZaRts (default) computes rise/transit/set. Required for customAngles.
+  final r = getSpa(
+    date, lat, lng, utcOffset,
+    functionCode: spaZaRts,
+    customAngles: [96.0, 102.0, 108.0],
+  );
+
+  print('Civil twilight begin:    ${r.angles[0].sunrise.toStringAsFixed(4)} h');
+  print('Nautical twilight begin: ${r.angles[1].sunrise.toStringAsFixed(4)} h');
+  print('Fajr (18°) begin:        ${r.angles[2].sunrise.toStringAsFixed(4)} h');
+  print('Fajr (18°) end:          ${r.angles[2].sunset.toStringAsFixed(4)} h');
+  print('Nautical twilight end:   ${r.angles[1].sunset.toStringAsFixed(4)} h');
+  print('Civil twilight end:      ${r.angles[0].sunset.toStringAsFixed(4)} h');
+}
+
+void main() {
+  printTwilight(40.7128, -74.006, -5.0); // New York, EST
+}
+```
--- a/README.md
+++ b/README.md
@ -3,6 +3,7 @@
 [![pub package](https://img.shields.io/pub/v/nrel_spa.svg)](https://pub.dev/packages/nrel_spa)
 [![CI](https://github.com/acamarata/nrel-spa-dart/actions/workflows/ci.yml/badge.svg)](https://github.com/acamarata/nrel-spa-dart/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Wiki](https://img.shields.io/badge/docs-wiki-blue)](https://github.com/acamarata/nrel-spa-dart/wiki)

 NREL Solar Position Algorithm for Dart and Flutter. Calculates solar zenith, azimuth, sunrise, sunset, and solar noon for any location and time. Pure Dart, zero dependencies.

@ -54,25 +55,9 @@ for (final angle in result.angles) {

 ## API

-### `getSpa(date, latitude, longitude, timezone, {...})`
+`getSpa(date, latitude, longitude, timezone, {...})` returns `SpaResult` with `zenith`, `azimuth`, `sunrise`, `solarNoon`, `sunset`, and `angles`. Use `calcSpa` for pre-formatted HH:MM:SS strings.

-| Parameter | Type | Default | Description |
-| --- | --- | --- | --- |
-| `date` | `DateTime` | required | UTC date and time |
-| `latitude` | `double` | required | Degrees (-90 to 90) |
-| `longitude` | `double` | required | Degrees (-180 to 180) |
-| `timezone` | `double` | required | Hours from UTC |
-| `elevation` | `double` | 0 | Meters above sea level |
-| `pressure` | `double` | 1013 | Atmospheric pressure (mbar) |
-| `temperature` | `double` | 15 | Temperature (Celsius) |
-| `deltaT` | `double` | 67 | TT - UT1 (seconds) |
-| `customAngles` | `List<double>` | [] | Zenith angles for rise/set |
-
-Returns `SpaResult` with `zenith`, `azimuth`, `sunrise`, `solarNoon`, `sunset`, and `angles`.
-
-## Architecture
-
-A direct port of the NREL Solar Position Algorithm (Reda & Andreas 2004) to Dart. The implementation follows the original algorithm's 142 intermediate calculations exactly. Custom zenith angles are computed in a single pass alongside the primary solar angles using the same ephemeris state.
+Full parameter reference and type definitions: [API Reference](https://github.com/acamarata/nrel-spa-dart/wiki/API-Reference).

 ## Compatibility