WooNooW/docs/ADDONS_GUIDE.md

# 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.*