=== SolarDawn Sunrise & Sunset Widget ===
Contributors: sandunmalinga
Tags: sunrise, sunset, weather, astronomy, golden hour, widget
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Display sunrise, sunset, day length, solar noon, golden hour, blue hour, and twilight times for selected locations.

== Description ==

SolarDawn Sunrise & Sunset Widget adds a responsive frontend card for sunrise and sunset information. It works in posts, pages, widget areas, Gutenberg shortcode blocks, and page builders through the `[solardawn_sunrise_sunset]` shortcode.

The widget can use a default country/state/city dropdown selection, manual latitude/longitude, shortcode location attributes, or optional visitor country detection by public IP. Sunrise, sunset, twilight, and daylight details are calculated locally from the selected coordinates and timezone, then cached with WordPress transients.

Features include:

* Sunrise and sunset times
* Solar noon
* Day length
* Golden hour morning and evening
* Blue hour morning and evening
* Civil, nautical, and astronomical twilight
* Light, dark, and sunrise gradient themes
* Country, state, and city dropdowns generated from the bundled location JSON
* Automatic latitude, longitude, and timezone detection from selected locations
* Optional visitor country detection, disabled by default

== Installation ==

1. Upload the `solardawn-sunrise-sunset-widget` folder to `/wp-content/plugins/`.
2. Activate "SolarDawn Sunrise & Sunset Widget" from the WordPress Plugins screen.
3. Go to the SolarDawn Sun Widget menu in wp-admin, or Settings > SolarDawn Sun Widget.
4. Choose your location mode, display options, theme, and cache duration.
5. Add `[solardawn_sunrise_sunset]` to a post, page, shortcode block, widget area, or page builder module.

== Shortcode Examples ==

Default settings:

`[solardawn_sunrise_sunset]`

Country:

`[solardawn_sunrise_sunset country="Sri Lanka"]`

Country, state, and city without manual coordinates:

`[solardawn_sunrise_sunset country="Sri Lanka" state="Western" city="Colombo"]`

City search within a country:

`[solardawn_sunrise_sunset country="Japan" city="Tokyo"]`

Manual coordinates:

`[solardawn_sunrise_sunset lat="6.9271" lon="79.8612" timezone="Asia/Colombo"]`

Custom title:

`[solardawn_sunrise_sunset country="United States" title="Today's Sun Times"]`

== Frequently Asked Questions ==

= Does this plugin add attribution links? =

No. The plugin does not render attribution links, hidden backlinks, footer links, or header links.

= Where does the widget get sunrise and sunset data? =

The widget calculates sunrise, sunset, solar noon, day length, twilight, golden hour, and blue hour locally from the selected latitude, longitude, timezone, and date.

= Does the plugin collect personal data? =

The default country dropdown and manual coordinate modes do not send visitor data to third-party services. When visitor country detection is enabled by an administrator, the plugin contacts ipapi.co to estimate the visitor's country from the visitor IP address. The full IP address is not stored in the database; only a salted hash is used in a transient cache key for 12 hours.

= What happens if sun data cannot be calculated? =

The widget shows a graceful frontend message and does not expose raw technical errors to visitors.

= Can I use this with Gutenberg or page builders? =

Yes. Use the shortcode in the Gutenberg shortcode block, classic editor, widget areas, or page builder shortcode modules.

== Screenshots ==

1. Sunrise gradient frontend widget card.
2. Admin settings page with location, display, theme, and cache options.
3. Mobile responsive widget layout.

== Privacy ==

This plugin calculates sunrise and sunset data locally from the selected latitude, longitude, timezone, and date.

Visitor country detection is disabled by default. When an administrator enables visitor country detection, the plugin sends the visitor IP address to ipapi.co to estimate the visitor's country. If visitor country detection is disabled, no request is sent to ipapi.co.

The plugin does not store the full IP address in the database. It stores only a salted hash in the transient key and caches the detected country for 12 hours.

== External services ==

This plugin can use one external service only when an administrator explicitly enables automatic visitor country detection.

Service name: ipapi

Service URL: `https://ipapi.co/`

Purpose: Used only to estimate the visitor's country when the admin enables automatic visitor country detection.

Data sent: The visitor IP address is sent to ipapi.co when country auto-detection is used.

When data is sent: Only when the widget/page loads and the auto-detect country feature is enabled.

If auto-detection is disabled, no request is sent to ipapi.co.

Terms of Service: `https://ipapi.co/terms/`

Privacy Policy: `https://ipapi.co/privacy/`


For a live sunrise and sunset calculator, visit:
https://earthpulsenow.com/sunrise-sunset

== Zip Packaging Instructions ==

1. Confirm the plugin folder is named `solardawn-sunrise-sunset-widget`.
2. Confirm the main plugin file is `solardawn-sunrise-sunset-widget.php`.
3. Zip the folder itself, not only the files inside it.
4. The final zip should contain `solardawn-sunrise-sunset-widget/solardawn-sunrise-sunset-widget.php` at the top level.
5. Upload the zip from WordPress Admin > Plugins > Add New > Upload Plugin.

== Testing Checklist ==

* Activate the plugin on WordPress 5.8 or newer.
* Confirm Settings > SolarDawn Sun Widget loads for administrators.
* Save settings in country mode and confirm the shortcode renders.
* Select a country, state, and city and confirm latitude, longitude, and timezone update automatically.
* Test a shortcode with `country`, `state`, and `city` attributes and confirm it renders without manual coordinates.
* Save settings in manual coordinate mode and confirm latitude, longitude, and timezone are used.
* Confirm visitor country detection is disabled by default.
* Enable visitor country detection and confirm the privacy note is visible in settings before using it.
* Confirm the widget works in default country mode without calling ipapi.co.
* Confirm ipapi.co is contacted only after visitor country detection is enabled.
* Confirm the widget renders in a post, page, Gutenberg shortcode block, and widget area.
* Check mobile layout below 680px width.
* Confirm no hidden footer or header links are added.

== WordPress.org Submission Checklist ==

* GPLv2 or later license is declared in the plugin header and readme.
* No hidden backlinks are present.
* No attribution link is rendered by the plugin.
* Optional IP geolocation behavior is documented.
* Inputs are sanitized and output is escaped.
* Admin settings use the WordPress Settings API and nonces from `settings_fields()`.
* Remote requests use `wp_remote_get()` only for the opt-in ipapi.co country detection feature.
* Assets are enqueued with WordPress APIs.
* No external CSS frameworks, font dependencies, or JavaScript libraries are required.
* Plugin files are namespaced/prefixed with `solardawn` or `SolarDawn`.

== Changelog ==

= 1.2.0 =

* Rebranded the plugin to SolarDawn Sunrise & Sunset Widget.
* Changed the text domain and plugin slug references to `solardawn-sunrise-sunset-widget`.
* Removed the attribution link feature.
* Removed external sunrise/sunset API settings and now calculate sun data locally.
* Documented optional ipapi.co visitor country detection and kept it disabled by default.

= 1.1.1 =

* Added a visible SolarDawn Sun Widget sidebar menu in wp-admin.
* Added a Settings shortcut on the Plugins page.

= 1.1.0 =

* Added country, state, and city location selection from bundled JSON data.
* Added automatic latitude, longitude, timezone, and display name resolution from selected locations.
* Added shortcode support for `state` and `city` attributes.

= 1.0.0 =

* Initial release.
