From 64e6fa6da09ff86b1c349b02adbf6035fa54e6c3 Mon Sep 17 00:00:00 2001
From: dwindown <dwinx.ramz@gmail.com>
Date: Thu, 20 Nov 2025 11:37:27 +0700
Subject: [PATCH] docs: Align METABOX_COMPAT with 3-level compatibility
 strategy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**Clarification: Level 1 Compatibility**

Following ADDON_BRIDGE_PATTERN.md philosophy:

**3-Level Compatibility Strategy:**

Level 1: Native WP/WooCommerce Hooks 🟢 (THIS IMPLEMENTATION)
- Community does NOTHING extra
- Plugins use standard add_meta_box(), update_post_meta()
- WooNooW listens and exposes data automatically
- Status: ❌ NOT IMPLEMENTED - MUST DO NOW

Level 2: Bridge Snippets 🟡 (Already documented)
- For non-standard behavior (e.g., Rajaongkir custom UI)
- Community creates simple bridge
- WooNooW provides hook system + docs
- Status: ✅ Hook system exists

Level 3: Native WooNooW Addons 🔵 (Already documented)
- Best experience, native integration
- Community builds proper addons
- Status: ✅ Addon system exists

**Key Principle:**
We are NOT asking community to create WooNooW-specific addons.
We are asking them to use standard WooCommerce hooks.
We LISTEN and INTEGRATE automatically.

**Example (Level 1):**
Plugin stores: update_post_meta($order_id, '_tracking_number', $value)
WooNooW: Exposes via API automatically
Result: Plugin works WITHOUT any extra effort

**Updated METABOX_COMPAT.md:**
- Added 3-level strategy overview
- Clarified Level 1 is about listening to standard hooks
- Emphasized community does NOTHING extra
- Aligned with ADDON_BRIDGE_PATTERN.md philosophy

**Confirmation:**
✅ Yes, we MUST implement Level 1 now
✅ This is about listening to WooCommerce bone
✅ Not about special integration
✅ Community uses standard hooks, we listen
---
 METABOX_COMPAT.md | 63 +++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 53 insertions(+), 10 deletions(-)

diff --git a/METABOX_COMPAT.md b/METABOX_COMPAT.md
index ce46878..cf86561 100644
--- a/METABOX_COMPAT.md
+++ b/METABOX_COMPAT.md
@@ -1,19 +1,62 @@
 # WooNooW Metabox & Custom Fields Compatibility
 
-## Current Status: ❌ NOT IMPLEMENTED
+## Philosophy: 3-Level Compatibility Strategy
 
-**Critical Gap:** Our SPA admin does NOT currently expose custom meta fields, metaboxes, or third-party plugin data injected via WordPress/WooCommerce hooks.
+Following `ADDON_BRIDGE_PATTERN.md`, we support plugins at 3 levels:
 
-### Example Use Case:
+### **Level 1: Native WP/WooCommerce Hooks** 🟢 (THIS DOCUMENT)
+**Community does NOTHING extra** - We listen automatically
+- Plugins use standard `add_meta_box()`, `update_post_meta()`
+- Store data in WooCommerce order/product meta
+- WooNooW exposes this data via API automatically
+- **Status: ❌ NOT IMPLEMENTED - MUST DO NOW**
+
+### **Level 2: Bridge Snippets** 🟡 (See ADDON_BRIDGE_PATTERN.md)
+**Community creates simple bridge** - For non-standard behavior
+- Plugins that bypass standard hooks (e.g., Rajaongkir custom UI)
+- WooNooW provides hook system + documentation
+- Community creates bridge snippets
+- **Status: ✅ Hook system exists, documentation provided**
+
+### **Level 3: Native WooNooW Addons** 🔵 (See ADDON_BRIDGE_PATTERN.md)
+**Community builds proper addons** - Best experience
+- Native WooNooW integration
+- Uses WooNooW addon system
+- Independent plugins
+- **Status: ✅ Addon system exists, developer docs provided**
+
+---
+
+## Current Status: ❌ LEVEL 1 NOT IMPLEMENTED
+
+**Critical Gap:** Our SPA admin does NOT currently expose custom meta fields from plugins that use standard WordPress/WooCommerce hooks.
+
+### Example Use Case (Level 1):
+```php
+// Plugin: WooCommerce Shipment Tracking
+// Uses STANDARD WooCommerce meta storage
+
+// Plugin stores data (standard WooCommerce way)
+update_post_meta($order_id, '_tracking_number', '1234567890');
+update_post_meta($order_id, '_tracking_provider', 'JNE');
+
+// Plugin displays in classic admin (standard metabox)
+add_meta_box('wc_shipment_tracking', 'Tracking Info', function($post) {
+    $tracking = get_post_meta($post->ID, '_tracking_number', true);
+    echo '<input name="_tracking_number" value="' . esc_attr($tracking) . '">';
+}, 'shop_order');
 ```
-Plugin: WooCommerce Shipment Tracking
-- Adds "Tracking Number" metabox to order edit page
-- Uses: add_meta_box('wc_shipment_tracking', ...)
-- Stores: update_post_meta($order_id, '_tracking_number', $value)
 
-Current Behavior: ❌ Field NOT visible in WooNooW admin
-Expected Behavior: ✅ Field should be visible and editable
-```
+**Current WooNooW Behavior:**
+- ❌ API doesn't expose `_tracking_number` meta
+- ❌ Frontend can't read/write this data
+- ❌ Plugin's data exists in DB but not accessible
+
+**Expected WooNooW Behavior (Level 1):**
+- ✅ API exposes `meta` object with all fields
+- ✅ Frontend can read/write meta data
+- ✅ Plugin works WITHOUT any bridge/addon
+- ✅ **Community does NOTHING extra**
 
 ---