=== Real Simple Autocomplete for WooCommerce ===
Contributors: SecretChord,eddr
Tags: woocommerce, google maps, autocomplete
Requires at least: 5.7
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.0.7
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Refresh-safe WooCommerce address autocomplete using Google Places API and optional OSM state matching.

== Description ==

Real Simple Autocomplete fills WooCommerce checkout street, city, state, postcode, and country fields using Google Places.

= Refresh-safe checkout updates =

A defining feature of RSAC is its checkout request guard. WooCommerce normally recalculates totals whenever address fields change. Autocomplete fills several dependent fields in quick succession, which can otherwise start overlapping recalculations using incomplete address data.

While the shopper types and selects an autocomplete result, RSAC temporarily suppresses same-origin WooCommerce checkout requests while continuing to allow Google Places and OSM traffic. After the complete address has been applied, RSAC releases the guard and allows one coherent checkout recalculation.

This helps prevent:

* Recalculations using partially populated addresses.
* Competing country, state, postcode, shipping, and tax updates.
* Checkout totals being calculated from stale field values.
* Classic checkout loading overlays becoming stuck after an intentionally blocked refresh.
* Excessive Store API batch requests in Checkout Blocks while autocomplete is active.

The request guard supports both classic checkout and Checkout Blocks and remains replaceable through `window.rsacCheckoutRequestGuard` for advanced integrations.

= Additional features =

* Legacy Google Places Autocomplete or opt-in Places API (New).
* Accessible, keyboard-navigable suggestions panel for Places API (New).
* International address-component handling and manually entered house-number preservation.
* Matches Google region codes and names directly to WooCommerce states, with an optional cached OSM fallback for unresolved regions.
* Missing house-number notification and administrator-scoped diagnostics.

== External services ==

This plugin does not send analytics or tracking data to the plugin author. It uses the following external services to provide address autocomplete and optional state or province matching. Depending on applicable law, site owners may need to describe these services in their privacy notice or obtain appropriate consent.

= Google Maps Platform and Places API =

Google Maps Platform is required for the plugin's address autocomplete functionality.

When an enabled checkout page loads, the shopper's browser requests the Google Maps JavaScript API. This request includes the site owner's Google API key, the configured language and region, and standard connection information such as the shopper's IP address and browser request data. As the shopper types in an enabled address field, the entered address text is sent to Google Places to obtain suggestions. Selecting a suggestion sends its Place identifier to Google to retrieve address components such as street, city, state, postcode, and country.

Google provides this service under its own policies:

* Google Maps Platform Terms of Service: https://cloud.google.com/maps-platform/terms/
* Google Privacy Policy: https://policies.google.com/privacy

= OpenStreetMap Nominatim =

OpenStreetMap Nominatim is optional. When enabled, it is used only if Google's state or province code and name cannot be matched directly to a WooCommerce state option.

In that fallback case, the latitude and longitude of the selected Google Place are sent to the public Nominatim reverse-geocoding service to obtain an ISO state or province code. With direct requests, the shopper's browser also sends standard connection information such as its IP address and browser request data. With the optional WordPress proxy cache enabled, the request is sent by the website server and also includes the site locale and a User-Agent containing the site URL. The plugin then caches only the country-and-region state-code mapping for 24 hours; it does not cache the shopper's complete address or Google Places responses.

OpenStreetMap Foundation provides this service under its own policies:

* Nominatim Usage Policy: https://operations.osmfoundation.org/policies/nominatim/
* OpenStreetMap Foundation Terms of Use: https://osmfoundation.org/wiki/Terms_of_Use
* OpenStreetMap Foundation Privacy Policy: https://osmfoundation.org/wiki/Privacy_Policy

== Frequently Asked Questions ==

= Why does RSAC pause WooCommerce checkout requests? =

Autocomplete changes multiple address fields as one operation. Allowing WooCommerce to refresh after every intermediate field can produce overlapping requests, incomplete shipping or tax calculations, and stuck loading states. RSAC pauses those requests until the selected address is fully applied, then releases the guard for the final checkout update. Google Places and OSM requests are not blocked.

= Why is a postcode missing for some addresses? =

Google Places returns a postcode only when the selected Place result contains a postal_code address component. This varies by address and region and is generally not controlled by the plugin API settings. When Google does not return a postcode, RSAC clears any postcode left from the previously selected address.

= How can I style the Places API (New) autocomplete panel? =

These controls apply only when Places API (New) is enabled; they do not affect the legacy Google Autocomplete widget. The dedicated "Places API (New) Panel Styling" settings section includes panel background, text, highlight colors, and z-index controls. For additional styling, target these selectors in your theme or custom CSS:

`.rsac-autocomplete-panel` - suggestions container.
`.rsac-autocomplete-option` - individual suggestion.
`.rsac-autocomplete-option.is-active` - keyboard-selected or highlighted suggestion.
`.rsac-google-maps-attribution` - Google Maps attribution.

The panel also supports these CSS custom properties:

`--rsac-panel-background`
`--rsac-panel-text`
`--rsac-panel-active`
`--rsac-panel-z-index`

= How can I collect a debug report? =

Select a Debug User and enable Browser debug logging in the plugin settings. Reproduce the checkout problem while logged in as that administrator, open the browser developer console, and run:

`rsacGetDebugReport()`

Copy the returned JSON when requesting support. The report can contain entered address data, but API keys and nonces are excluded or redacted. Run `rsacClearDebugReport()` before reproducing if you want to discard earlier entries.
