=== Harbor Checkout Fields for WooCommerce ===
Contributors: harborplugins
Tags: woocommerce, checkout, custom fields, additional checkout fields, block checkout
Requires at least: 6.4
Tested up to: 7.0
Stable tag: 1.0.1
Requires PHP: 8.2
Requires Plugins: woocommerce
WC requires at least: 8.9
WC tested up to: 10.9
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add custom fields to the WooCommerce block checkout: gift messages, delivery notes, PO numbers, and more. No code required.

== Description ==

**Harbor Checkout Fields for WooCommerce** lets you add custom fields to WooCommerce's block-based checkout without writing code.

Fields are collected at checkout, saved to order metadata using WooCommerce's HPOS-safe order API, and automatically appear in the admin order detail screen and in customer confirmation emails.

= Real-world use cases =

* **Gift message** - let customers include a message for the recipient
* **Delivery instructions** - collect access codes, gate instructions, or preferred drop-off spots
* **B2B purchase order number** - required for invoice reconciliation
* **How did you hear about us?** - a select dropdown for attribution tracking
* **Age confirmation checkbox** - required for alcohol, tobacco, or age-gated products
* **Special requests or dietary notes** - for food, events, or personalised items

= Free Features =

* Add text, email, phone, checkbox, and select (dropdown) fields to the block checkout
* Choose field location: Contact section, Address block, or Order section
* Mark fields as required or optional
* Add a placeholder prompt to select fields
* Drag-to-reorder fields in the admin settings page
* Field values saved to order metadata (HPOS-compatible)
* Values displayed in the admin order detail view (after billing address)
* Values displayed in customer and admin order confirmation emails
* No coding required - works out of the box

= How it works =

Fields are registered with WooCommerce's official block checkout additional-fields API (available in WooCommerce 8.9 and later). Values are stored on the order with the HPOS-safe order API and read back with `$order->get_meta()`, so no direct database queries are made against order tables.

= Requirements =

* WordPress 6.4 or later
* WooCommerce 8.9 or later (block checkout additional fields API)
* PHP 8.2 or later
* WooCommerce block checkout (not the legacy shortcode checkout)
* HPOS (High Performance Order Storage) compatible

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`
2. Activate the plugin through the Plugins screen in WordPress
3. Go to **WooCommerce > Checkout Fields** to add your first field (or click **Settings** in the plugin list)
4. Ensure you are using the WooCommerce block checkout (not the legacy shortcode checkout)

== Frequently Asked Questions ==

= Does this work with the classic/legacy WooCommerce checkout? =

No. This plugin targets the WooCommerce block checkout exclusively. For the legacy shortcode checkout, use WooCommerce's Checkout Field Editor or a similar plugin.

= Is this plugin compatible with HPOS? =

Yes. Field values are saved automatically by WooCommerce when a registered field is submitted. The plugin reads them via `$order->get_meta()`. No direct database queries against order tables are made.

= What WooCommerce version is required? =

WooCommerce 8.9 or later. The `woocommerce_register_additional_checkout_field()` function was introduced in WooCommerce 8.9.

= What PHP version is required? =

PHP 8.2 or later. PHP 8.0 and 8.1 reached end-of-life and are no longer supported.

= Where do field values appear? =

Field values appear in:

1. The WooCommerce admin order detail screen (after the billing address)
2. Customer and admin order confirmation emails

= What does the Location setting do? =

Location controls where the field appears in the block checkout:

* **Contact** - below the email and phone fields
* **Address** - inside the billing/shipping address block
* **Order** - below the order notes section

= Can I reorder fields? =

Yes. Drag the handle icon on the left of each field row in WooCommerce > Checkout Fields to change the display order.

= How many fields can I add? =

There is no hard limit enforced by this plugin. WooCommerce's own additional fields API handles rendering. Keeping the number of fields small helps keep checkout simple for customers.

= Will it slow down my store? =

No. Fields are registered server-side using WooCommerce's official API. No JavaScript is injected into the checkout frontend. The admin settings use lightweight AJAX.

= What happens to field data if I deactivate the plugin? =

Field values are stored as order meta on each order and will remain in your database. If you reactivate the plugin, historical field values will be visible again. Deleting a field from the settings page removes it from future checkouts and from the order and email displays; the stored values are not deleted and remain in the database.

= Does it work with Stripe, PayPal, and other payment gateways? =

Yes. Fields are rendered and validated by the WooCommerce block checkout before payment is processed. They are compatible with all major payment gateways.

= Is this compatible with popular page builders and themes? =

Yes. Because this plugin uses WooCommerce's official block checkout extensibility API, it works with any theme that uses the standard WooCommerce block checkout.

== Screenshots ==

1. Admin settings page with field list and drag-to-reorder
2. Add Field form with type and location options
3. Custom field displayed in the block checkout
4. Field value shown in the admin order view
5. Field value shown in the order confirmation email

== Support ==

For help with the plugin, post in the [WordPress.org support forum](https://wordpress.org/support/plugin/harbor-checkout-fields-for-woocommerce/) or email support@harborplugins.com.

== Changelog ==

= 1.0.1 =
* Fix: a conditionally-required Pro field could be bypassed by omitting it from the checkout request
* Fix: Pro conditional logic had no effect on fields in the Address section
* Fix: conditional fields became required for every shopper if the Pro licence lapsed; they now degrade to optional
* Fix: saving a field or restoring a field order without changing anything reported a save error
* Fix: an unticked checkbox stored as a boolean is now shown as "No" instead of being omitted
* Fix: CSV export dropped the shipping value of an Address field when it differed from the billing value
* Fix: CSV export could embed a PHP deprecation notice in the downloaded file on PHP 8.4+
* Fix: the 60/minute rate limit behaved as 60 per uninterrupted session and could lock out an active admin
* Fix: keyboard focus was lost when the Add Field panel closed and after a rejected reorder
* Fix: a reorder rejected by the server was still announced to screen readers as successful
* Fix: clicking Add Field during the panel's closing animation appeared to do nothing

= 1.0.0 =
* Add text, email, phone, checkbox, and select fields to the WooCommerce block checkout
* Choose field location: Contact, Address, or Order section
* Mark fields as required or optional; add a placeholder prompt to select fields
* Drag-to-reorder fields with persistence via AJAX
* AJAX-powered add, edit, delete, and reorder - no page reloads
* Inline delete confirmation; no browser alert dialogs
* Duplicate label detection on both add and edit forms
* Select field options editor (value|Label format, one per line)
* Checkbox fields are never stored as required (WooCommerce restriction)
* HPOS-safe: field values read via `$order->get_meta()`, no direct DB queries
* HPOS and block checkout compatibility declared to WooCommerce
* Field values displayed in admin order detail view (after billing address)
* Field values displayed in customer and admin confirmation emails (HTML + plain text)
* AJAX write operations rate-limited to 60 requests per minute per user
* Empty state shown when no fields exist; hidden when at least one is added
* Toast notifications with aria-live screen reader announcement on every action
* Focus returns to Edit button when edit form is cancelled (keyboard/SR navigation)
* Full accessibility: aria-live regions, aria-expanded, role="status/alert" attributes
* GitHub Actions CI: PHPUnit matrix (PHP 8.2/8.3/8.4), PHPCS (WordPress Coding Standards), Playwright E2E
* Unit tests across field registry, storage, admin settings, and sanitisation, plus Playwright E2E coverage
* Requires PHP 8.2 or later (PHP 8.0/8.1 are end-of-life)

== Upgrade Notice ==

= 1.0.1 =
Recommended for all users. Fixes validation, display, and accessibility bugs; Pro users should update to restore conditional-logic enforcement.

= 1.0.0 =
Initial release.
