=== Sri Lankan Cities for WooCommerce ===
Contributors: lakshan12
Tags: woocommerce, sri lanka, checkout, districts, postcode
Requires at least: 6.5
Tested up to: 7.0
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Adds Sri Lanka's 25 districts to WooCommerce checkout, suggests cities for the chosen district, and autofills postal codes.

== Description ==

WooCommerce ships Sri Lanka with no districts and the State field hidden. This plugin makes checkout work the way Sri Lankan addresses actually work: *101, Main Street, Negombo, Gampaha, 11500, Sri Lanka*.

* Adds all **25 districts** as a required **District** dropdown, keyed by ISO 3166-2:LK codes so couriers and shipping plugins interoperate.
* Suggests **cities for the selected district** while the customer types — 288 verified cities across all 25 districts.
* **Autofills the postal code** when a known city is picked — still editable, and it never overwrites a code the customer typed themselves.
* Lets you build **district-based shipping zones** (WooCommerce → Settings → Shipping → Add zone → pick districts).
* Works on **both** the classic (shortcode) checkout and the block checkout.

= Safety and design =

* **No external services.** No data leaves your site, nothing is tracked, no account is needed.
* No AJAX endpoints, no database writes, no extra checkout fields — WooCommerce validates the district server-side automatically.
* Everything fails safe: without WooCommerce the plugin does nothing; with JavaScript blocked, the district dropdown still works and city/postcode are normal manual fields.
* Block-checkout updates go through WooCommerce's official wp.data store API.

= Data provenance =

Every autofilled postal code was verified against Sri Lanka Post and independent directories (July 2026). Cities whose codes could not be fully verified are left out — for those, the city field simply works as a plain text box.

== Installation ==

1. Install and activate from Plugins → Add New Plugin (or upload the zip via Upload Plugin).
2. WooCommerce 8.9 or newer must be active.
3. Done — districts, city suggestions and postcode autofill work immediately on checkout. The plugin has no settings page of its own; the **Settings** link on the Plugins screen takes you to WooCommerce's shipping settings, where the districts appear as zone regions.

**Upgrading from the code-snippet version:** if you previously installed this as a snippet (FluentSnippets, a child theme's functions.php, or an mu-plugin file), remove that copy BEFORE activating the plugin. Both loaded at once causes a duplicate-function PHP error.

== Frequently Asked Questions ==

= How do I add my own cities? =

Use the `slwc_city_data` filter from your child theme or a small snippet:

`
add_filter( 'slwc_city_data', function ( $data ) {
    $data['LK-12']['My Village'] = '11123'; // district code => city => postcode
    return $data;
} );
`

District keys are ISO 3166-2:LK codes (the full list is in the District dropdown at checkout). Keep postcodes as quoted 5-digit strings — leading zeros matter.

= Does it work with the block checkout? =

Yes. Both the classic shortcode checkout and the block checkout are supported; block updates go through WooCommerce's official wp.data store API.

= What if a customer's city is not in the list? =

Nothing breaks: the city field keeps working as a normal text box and the customer types their postcode manually.

= Can I ship by district? =

Yes — the districts appear as regions in WooCommerce → Settings → Shipping → Add zone, so you can price shipping per district.

== Screenshots ==

1. Classic checkout — the required District dropdown with all 25 Sri Lankan districts.
2. Pick a known city and the postal code fills in automatically — shipping switches to the matching district zone.
3. The block checkout is fully supported: district, city suggestions and postcode autofill.
4. Ship by district — districts appear as regions in WooCommerce → Settings → Shipping.

== Changelog ==

= 1.0.0 =
* Initial release: 25 districts at checkout, 288-city suggestions, postcode autofill, district shipping zones, classic + block checkout.

== Upgrade Notice ==

= 1.0.0 =
If you used the old code-snippet version, remove the snippet before activating the plugin — both at once causes a duplicate-function error.
