=== Kuwadema – Kuwait Delivery Areas for WooCommerce ===
Contributors: softx
Tags: delivery, delivery-fee, kuwait, checkout, woocommerce
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 1.2.6
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Area-based delivery fees for WooCommerce. Bilingual (AR/EN), classic and block checkout, free-delivery thresholds.

== Description ==

Kuwadema adds an area-based delivery fee system to WooCommerce. Define your delivery cities and areas, set a price per area, and customers pick their area at checkout — the delivery fee is added to the cart automatically.

Built for stores in Kuwait (ships with a one-click default dataset of Kuwait governorates and 80+ areas), but works for any country: add your own cities and areas under any billing country.

This plugin requires WooCommerce. It is an independent extension and is not affiliated with or endorsed by WooCommerce or Automattic.

= Features =

* **Cities & areas manager** — add, edit, sort, and toggle delivery cities and areas from a dedicated admin screen with inline editing.
* **Per-area delivery fees** — each area has its own delivery price.
* **Free-delivery threshold** — set a minimum order per area; carts at or above it get free delivery, with a clear "Free (orders over X)" label.
* **Minimum order floor** — optionally require a minimum cart total before an area can be selected.
* **Classic + block checkout** — a searchable area picker on the classic checkout and native support for the WooCommerce Cart & Checkout Blocks (Additional Checkout Fields API).
* **Bilingual (Arabic / English)** — every city and area stores both names; the checkout shows the right one for the active language. WPML and Polylang compatible.
* **Field layout control** — reorder, show/hide, and set required/width for checkout billing fields from a drag-and-drop settings card, including Kuwait-specific address fields (Block, Jaddah, House No., Floor, Civil ID) with per-country visibility.
* **Delivery notes** — per-area notes stored in both languages.
* **CSV export** — download all cities, areas, and prices as a UTF-8 CSV backup.
* **Multi-currency compatible** — converts the fee for Curcy (WooCommerce Multi Currency), WOOCS, WPML/WCML, and Aelia Currency Switcher.
* **HPOS compatible** — order meta is written through the WooCommerce CRUD API and works with High-Performance Order Storage.
* **Cache-safe checkout** — emits no-cache signals (WP Super Cache, W3TC, LiteSpeed, Autoptimize) so delivery fees never render from a stale cached page.
* **Data-preserving by default** — deleting the plugin keeps your data unless you explicitly opt in to a wipe via a wp-config.php constant.

== Installation ==

1. Upload the plugin ZIP via Plugins → Add New → Upload Plugin, or unzip it into `/wp-content/plugins/`.
2. Activate the plugin through the Plugins screen.
3. Make sure WooCommerce is active (required for checkout integration).
4. Go to **Delivery Manager → Import** and click **Load default Kuwait dataset**, or add your own cities and areas under **Delivery Manager → Cities / Areas**.
5. Prices and the area picker appear on your checkout immediately.

== Frequently Asked Questions ==

= Does it work outside Kuwait? =

Yes. Kuwait is just the default dataset. You can add cities and areas under any billing country from Delivery Manager → Cities, and choose which countries see the area picker under Settings → Delivery Countries.

= Does it support the WooCommerce block checkout? =

Yes. The area picker is registered through the WooCommerce Additional Checkout Fields API (WooCommerce 8.9+) and the delivery fee is applied to block-checkout carts as well.

= What about minimum order amounts? =

Each area has a free-delivery threshold: carts at or above it get free delivery. Set it to 0 to always charge the delivery fee. A separate optional "required minimum order" field blocks checkout below a hard floor.

= Will I lose my data when updating or deleting the plugin? =

No. Updating never touches your data. Deleting the plugin also preserves all data by default — a full wipe only happens if you add `define( 'KUWADEMA_DROP_DATA_ON_UNINSTALL', true );` to wp-config.php before deleting.

= Is it compatible with multi-currency plugins? =

Yes — Curcy (WooCommerce Multi Currency), WOOCS, WPML/WCML, and Aelia Currency Switcher are converted automatically. WooCommerce Payments multi-currency is handled natively.

== Screenshots ==

1. Delivery areas manager with inline editing.
2. Cities manager.
3. Checkout area picker with live delivery fee.
4. Settings — field layout and delivery countries.

== Changelog ==

= 1.2.6 =
* New: quarter, third and three-quarter field widths in Field Layout, in float, Impreza and Tocaan Checkout Builder layouts.
* Changed: default layout — Country ½ | Area ½, Block ¼ | Street ½ | House ¼, Jaddah ⅓ | Floor ⅓ | Apartment ⅓ (Apartment now shown, labelled "Apartment No." / رقم الشقة). Use "Restore recommended layout" to apply it to an existing site.
* Fix: the Apartment No. field shows its label like its neighbours (WooCommerce hides the Address line 2 label and uses a long placeholder).
* Fix: Impreza's order summary no longer shrinks to its content in RTL; it matches the width of the boxes below it.

= 1.2.5 =
* Fix: Field Layout widths now apply in grid-based checkout layouts (e.g. Impreza's checkout element) — half-width fields share a row and full-width fields span it, on any number of grid columns.
* Changed: default layout is Block | Street, Jaddah | House, then Floor; the Street label reads "Street name or number" (اسم أو رقم الشارع).

= 1.2.4 =
* Changed: the standard billing City is filled with the area and the billing State with the governorate, always in Arabic, so orders filter and report consistently (State only where WooCommerce has no fixed state list; typed values are never overwritten).
* Fix: printed addresses no longer repeat the area / governorate as City / State when the Area and Governorate lines already show them.
* Fix: a custom Country label no longer flips back to "Country / Region" right after the checkout loads (WooCommerce's address script re-applied its own label).
* Fix: custom labels also survive country-specific WooCommerce labels when the customer changes country.
* Fix: half-width Kuwait fields (e.g. Jaddah | House) fill their half of the row inside Tocaan Checkout Builder's grid instead of shrinking to a quarter.

= 1.2.3 =
* New: the phone field shows the billing country's calling code (e.g. +965) and saves numbers in international form (classic checkout; can be turned off).
* New: "Restore recommended layout" in Field Layout — Name, Phone, Email (optional), Country, Area, Block | Jaddah, Street, House | Floor — keeping custom labels.
* New: option to show each area's delivery price in the area list; prices are hidden by default.
* Changed: default layout pairs Block with Jaddah and House with Floor, places Street between them, and makes Email optional.
* Improved: an "Edit" button on each area row, and clicking a row opens it for editing.

= 1.2.2 =
* New: Import from CSV — restore or update cities and areas from an exported file, with "add & update" or "replace" modes, a check-only dry run, and row-by-row error reporting. Nothing is saved if any row has a problem.
* New: the importer copes with Excel quirks — Windows-1256 and UTF-16 files, ";" separators, decimal commas, Arabic-Indic digits, currency text and TRUE/FALSE flags.
* New: separate Arabic and English custom labels per checkout field, chosen by the page language (WPML, Polylang or the site language).
* New: compatibility with Tocaan Invoice Print — area, block, jaddah, house and floor now print on invoices.
* Fix: Kuwadema fields no longer squeeze into one row when Tocaan Checkout Builder's grid layout is active.
* Fix: the export now includes cities without areas and guards cells against spreadsheet formula injection.
* Improved: Areas and Cities screens use the full screen width.

= 1.2.1 =
* Improved: area row actions redesigned as consistent frameless icon buttons (edit, delete, cancel) with hover colours and clear focus rings; compact Save button.
* Improved: lighter copy / apply-to-all icons in the areas table.

= 1.2.0 =
* New: first-run Setup Wizard — pick delivery countries, import the Kuwait governorates and areas in one click, and choose how delivery is charged.
* New: the fee is labelled "Delivery fee" inside the WooCommerce store country and "Shipping fee" for other destinations (translatable, filterable via `kuwadema_fee_label`).
* New: delivery details (block, jaddah, house, floor, city, area, fee) appear in the official WooCommerce mobile app through the REST API.
* New: complete Arabic translation, including checkout-specific field labels (اختر المنطقة، رقم القطعة، اسم الشارع، رقم الجادة، رقم المنزل، رقم الدور).
* New: searchable country pickers using WooCommerce's selectWoo.
* New: styled confirmation dialog replaces the browser's native confirm prompts.
* Improved: Areas manager rebuilt as a WordPress-native, direction-aware (LTR and RTL) interface with meaningful icons.
* Improved: prices follow WooCommerce currency position, decimals and separators; country lists follow WooCommerce shipping locations.
* Improved: Block No., Jaddah and Civil ID open the numeric keypad on mobile in the block checkout.

= 1.1.4 =
* Block checkout: fixed order placement failing with "kuwadema/area is not of type string" (Store API field schema requires string values).
* Block checkout: the delivery area and Kuwait address fields now use WooCommerce's official conditional field rules — hidden/optional for countries without delivery and while local pickup is selected (with a server-side fallback on older WooCommerce).
* Block checkout: area selection now refreshes cart totals through the official Store API extension round-trip (extensionCartUpdate), so the delivery fee appears instantly.
* Block checkout: City / Postcode / Apartment now follow the Field Layout show/required toggles via the WooCommerce country locale, matching the classic checkout.
* Block checkout: area options now cover every configured delivery country, not only Kuwait.
* Introduced a shared order-data layer: both checkouts snapshot the same canonical meta (country, city id/name, area id/name, server-calculated fee) and integrations can read it through the `kuwadema_order_delivery_data` filter.
* Server-side validation now verifies the full relationship (billing country → active city → active area) on both checkouts, so a stale or cross-country area id can never be charged or saved.
* Virtual-only carts no longer require a delivery area and are never charged a delivery fee; choosing local pickup also skips the fee (filterable).
* The standard WooCommerce billing city is filled with the selected area name when the customer left it empty, so couriers and shipping integrations reading the standard address get a usable city (filterable via `kuwadema_fill_billing_city`).
* Order emails now render the delivery details in plain-text emails too, and the duplicated "Delivery Area" row was removed from order/email/admin delivery tables.

= 1.1.3 =
* Reduced normal delivery-area changes from multiple totals requests to one WooCommerce refresh.
* Kept a single delayed direct fallback for themes that suppress WooCommerce checkout events.
* Cancelled stale session and fallback requests when customers change areas quickly.
* Added request-local caching for repeated area, city and country database reads.
* Made the theme fallback use WooCommerce's nonce and complete checkout payload so third-party pricing hooks stay synchronized.

= 1.1.2 =
* Added named area/city choices to Tocaan conditional rules.
* Reserved Kuwadema checkout keys to prevent duplicate or conflicting custom fields.
* Added a visible connected-integration status in Checkout Builder.

= 1.1.1 =
* Added first-class Tocaan Checkout Builder compatibility.
* Checkout Builder now owns shared WooCommerce field widths and ordering when both plugins are active.
* Added live Kuwadema area and governorate/city option sources and conditional-logic sources to Checkout Builder.
* Kept Kuwadema delivery validation, sessions, fees and order metadata as the delivery source of truth.

= 1.1.0 =
* New: redesigned admin interface — clean white professional look with a single accent color across the Areas manager, Cities, Settings, and Import/Export pages.
* New: rename checkout fields from Settings → Field Layout — a Custom Label box per field; leave it empty to keep the default name. Custom labels can be translated per language via Polylang / WPML string translation.
* New: each row in Field Layout now shows whether the field is a native WordPress / WooCommerce field and its native WooCommerce name (e.g. billing_first_name — First name), or a plugin-specific field.
* Fix: the phone field's Show / Required toggles now also apply to the block-based checkout — previously phone could show as "(optional)" there even when marked required in the settings. Field Layout now overrides WooCommerce's own phone setting.
* Custom labels flow through checkout (classic and block address fields), validation messages, order details, emails, and PDF invoices. On block checkout the Email label stays WooCommerce's own.
* Fix (WPML/Polylang): area and city names loaded over AJAX came back in the site's default language instead of the language the customer was browsing in. Changing the country at checkout reloaded the area list in the wrong language while the rest of the page stayed correct. The plugin now records the visitor's language, sends it with every AJAX request, and switches WPML to it server-side.
* Fix (WPML): language detection used the ICL_LANGUAGE_CODE constant, which WPML has deprecated and which does not follow runtime language switches such as sending an order email in the customer's language. It now uses the documented wpml_current_language filter, and passes an explicit language code to WPML String Translation.
* Fix: Arabic content was only served when the language code was exactly "ar", so stores whose WPML language code is a regional variant (for example ar-kw) saw English everywhere. Regional variants and third languages now resolve correctly.
* Fix: a city with only one of its two names filled in rendered a blank group heading in the area picker; the empty side now falls back to the other language.
* Fix: field labels translated in WPML String Translation had no effect at checkout — labels were resolved once, very early in the request, and reused for the rest of it. They are now resolved at render time, in the request's actual language.
* Fix: admin-typed custom labels are registered with WPML the first time they are used, so they translate even on block checkout, which resolves its labels before the usual registration hook runs.
* New: the plugin now loads its text domain explicitly and ships languages/kuwadema.pot, so .mo files in wp-content/languages/plugins/ and WPML's plugin-localization scan both work.

= 1.0.0 =
* Initial release on WordPress.org.
* Cities & areas manager with per-area delivery fees and free-delivery thresholds.
* Classic and block checkout integration with a searchable, bilingual area picker.
* Field layout control for checkout billing fields with per-country visibility.
* CSV export and one-click default Kuwait dataset.
* Multi-currency and HPOS compatibility.

== Upgrade Notice ==

= 1.2.0 =
Adds a setup wizard, Arabic translation, delivery/shipping fee labels and WooCommerce mobile app support.

= 1.1.0 =
Adds custom field labels with native WooCommerce field names, and fixes the phone Required toggle on block checkout.

= 1.0.0 =
Initial release.
