docs: consolidate markdown documentation into master guides and remove obsolete files

2026-03-12 04:19:25 +07:00
parent ab10c25c28
commit 3f2019bc7c
47 changed files with 603 additions and 18841 deletions
--- a/docs/ADDONS_GUIDE.md
+++ b/docs/ADDONS_GUIDE.md
@@ -0,0 +1,185 @@
+# WooNooW Addon & Module Development Guide
+
+**Version:** 2.0.0  
+**Status:** Production Ready
+
+This document is the single source of truth for extending WooNooW. It covers everything from basic code snippets (Bridge Patterns) to full-featured React SPAs (Addon Modules).
+
+---
+
+## 📋 Table of Contents
+
+1. [Philosophy & Architecture](#philosophy--architecture)
+2. [Addon Types & Integration Levels](#addon-types--integration-levels)
+   - Level 1: Vanilla JS / Bridge Patterns
+   - Level 2: React Runtime Expansion (Recommended)
+   - Level 3: Slot-Based Components
+3. [Developing a Full Addon](#developing-a-full-addon)
+   - Registration
+   - Settings & Options
+   - The Hook System
+4. [Addon & Built-in Module Unification](#addon--built-in-module-unification)
+5. [Examples](#examples)
+
+---
+
+## 1. Philosophy & Architecture
+
+**WooNooW Core = Zero Addon Dependencies**
+
+We don't integrate specific addons (like shipping or payment plugins) directly into WooNooW core. Instead, we provide:
+1. **Hook system** for external addons to extend functionality.
+2. **Exposed React Runtime** so addons don't have to bundle heavy libraries.
+3. **Unified Module Registry** where built-in features (like Affiliates, Newsletters) and external addons share the same UI and enablement toggles.
+
+---
+
+## 2. Addon Types & Integration Levels
+
+### Level 1: Vanilla JS / Bridge Patterns (Basic)
+Use this for simple snippets to make existing WooCommerce plugins (e.g. Rajaongkir) work with WooNooW.
+
+```javascript
+// Wait for WooNooW to load
+window.addEventListener('woonoow:loaded', function() {
+  window.WooNooW.hooks.addFilter('woonoow_order_form_after_shipping', function(container, formData) {
+    const div = document.createElement('div');
+    div.innerHTML = `<select id="custom-dest"><option>Select...</option></select>`;
+    container.appendChild(div);
+    return container;
+  });
+});
+```
+
+### Level 2: Exposed React Runtime (Recommended)
+WooNooW exposes `React`, `ReactDOM`, its `hooks`, and its `components` on `window.WooNooW`. This allows addons to build rich UIs without bundling React.
+
+**Webpack/Vite Setup (Externals):**
+```javascript
+// vite.config.js
+export default {
+  build: {
+    rollupOptions: {
+      external: ['react', 'react-dom'],
+      output: {
+        globals: {
+          react: 'window.WooNooW.React',
+          'react-dom': 'window.WooNooW.ReactDOM'
+        }
+      }
+    }
+  }
+};
+```
+
+**Usage:**
+```typescript
+const { React, hooks, components } = window.WooNooW;
+const { addFilter } = hooks;
+const { Select } = components;
+
+function CustomField({ formData, setFormData }) {
+  return <Select label="Custom" onChange={(val) => setFormData({...})} />;
+}
+
+addFilter('woonoow_order_form_after_shipping', (container, props) => {
+  const root = window.WooNooW.ReactDOM.createRoot(container);
+  root.render(<CustomField {...props} />);
+  return container;
+});
+```
+
+### Level 3: SPA Route Injection (Admin Pages)
+You can inject entire new pages into the WooNooW admin SPA.
+```php
+add_filter('woonoow/spa_routes', function($routes) {
+    $routes[] = [
+        'path'          => '/my-addon',
+        'component_url' => plugin_dir_url(__FILE__) . 'dist/MyPage.js',
+        'title'         => 'My Addon',
+    ];
+    return $routes;
+});
+```
+
+---
+
+## 3. Developing a Full Addon
+
+### Step 1: Registration
+Register the addon via PHP filters so WooNooW knows it exists.
+
+```php
+add_filter('woonoow/addon_registry', function($addons) {
+    $addons['my-addon'] = [
+        'id'           => 'my-addon',
+        'name'         => 'My Custom Addon',
+        'description'  => 'Does something awesome.',
+        'version'      => '1.0.0',
+        'category'     => 'shipping', // Auto-groups in the UI
+        'icon'         => 'truck', 
+        'spa_bundle'   => plugin_dir_url(__FILE__) . 'dist/addon.js',
+        'has_settings' => true, // Enables the ⚙️ icon
+    ];
+    return $addons;
+});
+```
+
+### Step 2: Settings & Options
+By declaring `'has_settings' => true`, WooNooW expects your settings to live at `/settings/modules/{addon_id}`.
+
+**Option A: Schema-based (No React needed)**
+```php
+add_filter('woonoow/module_settings_schema', function($schemas) {
+    $schemas['my-addon'] = [
+        'api_key' => ['type' => 'text', 'label' => 'API Key'],
+    ];
+    return $schemas;
+});
+```
+
+**Option B: Custom React Settings Component**
+```php
+// In addon_registry registration array:
+'settings_component' => plugin_dir_url(__FILE__) . 'dist/Settings.js',
+```
+Access data in React:
+```typescript
+const { useModuleSettings } = window.WooNooW.hooks;
+const { settings, updateSettings } = useModuleSettings('my-addon');
+```
+
+---
+
+## 4. Addon & Built-in Module Unification
+
+**Concept:** External addons and built-in features (e.g. Affiliates, Newsletters) look and act exactly the same in the Admin UI.
+- Both use `ModuleRegistry`.
+- Both generate dynamic categories (e.g. "Marketing", "Shipping").
+- Both persist settings to `woonoow_module_{id}_settings`.
+
+---
+
+## 5. Hook System Reference
+
+### Frontend Extension Hooks
+```typescript
+// Add fields
+'woonoow_order_form_after_billing'
+'woonoow_order_form_after_shipping'
+'woonoow_order_form_custom_sections'
+
+// Validation & Data Modification
+'woonoow_order_form_validation'
+'woonoow_order_form_data'
+```
+
+### Backend Action Hooks
+```php
+apply_filters('woonoow_before_shipping_calculate', $shipping_data);
+apply_filters('woonoow_after_shipping_calculate', $rates, $shipping_data);
+apply_filters('woonoow_shipping_data', $data);
+```
+
+---
+*For specific implementation examples, consult the `examples/` directory in the repository.*