From 24be6eb6560eebee59724a4dc9f6288b60d8d8c7 Mon Sep 17 00:00:00 2001
From: Dwindi Ramadhana <dwindown@DwMacMiniM4.local>
Date: Wed, 3 Jun 2026 22:57:57 +0700
Subject: [PATCH] docs: Add custom checkout fields and address formatting
 documentation

---
 docs/developer/addons/checkout-fields.mdx | 87 +++++++++++++++++++++++
 docs/hooks/frontend.mdx                   |  8 +++
 2 files changed, 95 insertions(+)
 create mode 100644 docs/developer/addons/checkout-fields.mdx

diff --git a/docs/developer/addons/checkout-fields.mdx b/docs/developer/addons/checkout-fields.mdx
new file mode 100644
index 0000000..871306d
--- /dev/null
+++ b/docs/developer/addons/checkout-fields.mdx
@@ -0,0 +1,87 @@
+---
+title: Custom Checkout Fields
+description: How to extend WooNooW checkout with custom fields and address formatting
+date: 2024-06-03
+---
+
+## Overview
+
+WooNooW fully integrates with the standard `woocommerce_checkout_fields` filter. This means any plugin that modifies or adds fields to WooCommerce checkout will generally work seamlessly with the WooNooW SPA checkout and address book features.
+
+However, WooNooW introduces several powerful SPA-specific enhancements that you can take advantage of when writing integrations or custom plugins (such as RajaOngkir).
+
+---
+
+## Supported Field Properties
+
+When defining a custom field via `woocommerce_checkout_fields`, WooNooW respects the standard WooCommerce properties (like `type`, `label`, `required`, `default`, etc.), plus it adds a few specialized ones for modern React components.
+
+### `form-row-wide` Class Support
+
+The SPA natively converts WooCommerce field classes to Tailwind grid classes:
+*   Adding `'form-row-wide'` to the `class` array of a field will automatically apply `md:col-span-2`, forcing the field to take up **100% width** on the checkout and address editing forms.
+*   If `'form-row-wide'` is omitted, the field typically spans **50% width** on tablet and desktop screens (`md:col-span-1`).
+
+### Hidden Fields
+
+If you want to hide a standard field (e.g., `billing_last_name` or `shipping_country`), you can do so in two ways that WooNooW understands:
+1.  Change the field's type: `$fields['billing']['billing_last_name']['type'] = 'hidden';`
+2.  Add a hidden class: `$fields['billing']['billing_last_name']['class'][] = 'hidden';`
+
+> **Tip**: If you hide `last_name`, you might want to make `first_name` take up the full row. You can easily do this by adding `'form-row-wide'` to the `first_name` class array!
+
+### `searchable_select` Field Type (New in WooNooW)
+
+WooNooW introduces a new `searchable_select` type which renders an accessible, auto-complete dropdown component with API search capabilities. This is perfect for deeply nested address data like subdistricts or provinces.
+
+**Example:**
+```php
+$fields['billing']['billing_destination_id'] = [
+    'type'            => 'searchable_select',
+    'label'           => __('Destination', 'woonoow'),
+    'required'        => true,
+    'search_endpoint' => '/rajaongkir/destinations',
+    'search_param'    => 'search',
+    'min_chars'       => 3,
+    'placeholder'     => 'Type to search destination...',
+];
+```
+
+*   **`search_endpoint`**: The WooNooW API endpoint to call (e.g., `GET /wp-json/woonoow/v1/rajaongkir/destinations?search=query`).
+*   **`search_param`**: The query parameter name (default: `'search'`).
+*   **`min_chars`**: The minimum characters a user must type before firing the API request.
+
+The endpoint must return an array of objects with `value` and `label`:
+```json
+[
+  { "value": "123", "label": "Jakarta Selatan, DKI Jakarta" },
+  { "value": "124", "label": "Jakarta Pusat, DKI Jakarta" }
+]
+```
+
+---
+
+## Custom Address Formatting
+
+If you introduce custom fields (like a RajaOngkir destination ID), you will likely want to format how the address is displayed on the "My Account" address cards and the "Checkout" saved address selector.
+
+WooNooW provides the `woonoow_format_address` filter for this exact purpose.
+
+**Example:**
+```php
+add_filter('woonoow_format_address', function($formatted, $address) {
+    $parts = [];
+    $parts[] = $address['first_name'] . ' ' . $address['last_name'];
+    $parts[] = $address['address_1'];
+    
+    // Append custom label saved by a searchable_select component
+    if (!empty($address['destination_id_label'])) {
+        $parts[] = $address['destination_id_label'];
+    }
+    
+    // The SPA uses whitespace-pre-wrap, so newlines render correctly
+    return implode("\n", array_filter($parts));
+}, 10, 2);
+```
+
+When `formatted_address` is provided, the SPA will automatically bypass its default layout and display your perfectly formatted, newline-separated string.
diff --git a/docs/hooks/frontend.mdx b/docs/hooks/frontend.mdx
index 605bc20..1d5331c 100644
--- a/docs/hooks/frontend.mdx
+++ b/docs/hooks/frontend.mdx
@@ -19,3 +19,11 @@ Modify the standard set of checkout fields recognized by the system.
 
 **Parameters:**
 *   `$keys` (array): List of field aliases (e.g., ['billing_first_name', ...]).
+
+### woonoow_format_address
+
+Allows modifying or overriding the displayed address format (e.g., for My Account address cards and checkout address selection cards). Useful for plugins like RajaOngkir where custom fields replace the default state/city fields.
+
+**Parameters:**
+*   `$formatted_address` (string): The initially formatted address string (usually empty by default).
+*   `$address` (array): The raw address data array containing all standard and custom address fields.