WooNooW/TAX_SETTINGS_DESIGN.md

# Tax Settings Design - WooNooW

## Philosophy: Zero Learning Curve

User should understand tax setup in 30 seconds, not 30 minutes.

---

## UI Structure

```
Tax Settings Page
├── [Toggle] Enable tax calculations
│   └── Description: "Calculate and display taxes at checkout"
│
├── When ENABLED, show:
│
├── Predefined Tax Rates [SettingsCard]
│   └── Based on store country from Store Details
│   
│   Example for Indonesia:
│   ┌─────────────────────────────────────┐
│   │ 🇮🇩 Indonesia Tax Rates             │
│   ├─────────────────────────────────────┤
│   │ Standard Rate: 11%                  │
│   │ Applied to: All products            │
│   │ [Edit Rate]                         │
│   └─────────────────────────────────────┘
│
├── Additional Tax Rates [SettingsCard]
│   ├── [+ Add Tax Rate] button
│   └── List of custom rates:
│       ┌─────────────────────────────────┐
│       │ Malaysia: 6%                    │
│       │ Applied to: All products        │
│       │ [Edit] [Delete]                 │
│       └─────────────────────────────────┘
│
├── Display Settings [SettingsCard]
│   ├── Prices are entered: [Including tax / Excluding tax]
│   ├── Display prices in shop: [Including tax / Excluding tax]
│   └── Display prices in cart: [Including tax / Excluding tax]
│
└── Advanced Settings
    └── Link to WooCommerce tax settings

```

---

## Predefined Tax Rates - Smart Detection

**Source:** WooCommerce General Settings → "Selling location(s)"

### Scenario 1: Sell to Specific Countries
If user selected specific countries (e.g., Indonesia, Malaysia):
```
Predefined Tax Rates
├── 🇮🇩 Indonesia: 11% (PPN)
└── 🇲🇾 Malaysia: 6% (SST)
```

### Scenario 2: Sell to All Countries
If user selected "Sell to all countries":
```
Predefined Tax Rates
└── Based on store country:
    🇮🇩 Indonesia: 11% (PPN)

Additional Tax Rates
└── [+ Add Tax Rate] → Shows all countries
```

### Scenario 3: Sell to Specific Continents
If user selected "Asia":
```
Suggested Tax Rates (Asia)
├── 🇮🇩 Indonesia: 11%
├── 🇲🇾 Malaysia: 6%
├── 🇸🇬 Singapore: 9%
├── 🇹🇭 Thailand: 7%
├── 🇵🇭 Philippines: 12%
└── 🇻🇳 Vietnam: 10%
```

### Standard Tax Rates by Country

| Country | Standard Rate | Note |
|---------|---------------|------|
| Indonesia | 11% | PPN (VAT) |
| Malaysia | 6% | SST |
| Singapore | 9% | GST |
| Thailand | 7% | VAT |
| Philippines | 12% | VAT |
| Vietnam | 10% | VAT |
| United States | 0% | Varies by state - user adds manually |
| European Union | 20% | Average - varies by country |

---

## User Flow

### Scenario 1: Indonesian Store (Simple)
1. User enables tax toggle
2. Sees: "🇮🇩 Indonesia: 11% (Standard)"
3. Done! Tax is working.

### Scenario 2: Multi-Country Store
1. User enables tax toggle
2. Sees predefined rate for their country
3. Clicks "+ Add Tax Rate"
4. Selects country: Malaysia
5. Rate auto-fills: 6%
6. Clicks Save
7. Done!

### Scenario 3: US Store (Complex)
1. User enables tax toggle
2. Sees: "🇺🇸 United States: 0% (Add rates by state)"
3. Clicks "+ Add Tax Rate"
4. Selects: United States - California
5. Enters: 7.25%
6. Clicks Save
7. Repeats for other states

---

## Add Tax Rate Dialog

```
Add Tax Rate
├── Country/Region [Searchable Select]
│   └── 🇮🇩 Indonesia
│       🇲🇾 Malaysia
│       🇺🇸 United States
│       └── California
│           Texas
│           New York
│
├── Tax Rate (%)
│   └── [Input: 11]
│
├── Tax Class
│   └── [Select: Standard / Reduced / Zero]
│
└── [Cancel] [Save Rate]
```

---

## Backend Requirements

### API Endpoints:
- `GET /settings/tax/config` - Get tax enabled status + rates
- `POST /settings/tax/toggle` - Enable/disable tax
- `GET /settings/tax/rates` - List all tax rates
- `POST /settings/tax/rates` - Create tax rate
- `PUT /settings/tax/rates/{id}` - Update tax rate
- `DELETE /settings/tax/rates/{id}` - Delete tax rate
- `GET /settings/tax/suggested` - Get suggested rates based on selling locations

### Get Selling Locations:
```php
// Get WooCommerce selling locations setting
$selling_locations = get_option('woocommerce_allowed_countries');
// Options: 'all', 'all_except', 'specific'

if ($selling_locations === 'specific') {
    $countries = get_option('woocommerce_specific_allowed_countries');
    // Returns array: ['ID', 'MY', 'SG']
}

// Get store base country
$store_country = get_option('woocommerce_default_country');
// Returns: 'ID:JB' (country:state) or 'ID'
```

### Predefined Rates Data:
```json
{
  "ID": {
    "country": "Indonesia",
    "rate": 11,
    "name": "PPN (VAT)",
    "class": "standard"
  },
  "MY": {
    "country": "Malaysia",
    "rate": 6,
    "name": "SST",
    "class": "standard"
  }
}
```

---

## Benefits

✅ **Zero learning curve** - User sees their country's rate immediately
✅ **No re-selection** - Store country from Store Details is used
✅ **Smart defaults** - Predefined rates are accurate
✅ **Flexible** - Can add more countries/rates as needed
✅ **Accessible** - Clear labels, simple toggle
✅ **Scalable** - Works for single-country and multi-country stores

---

## Comparison to WooCommerce

| Feature | WooCommerce | WooNooW |
|---------|-------------|---------|
| Enable tax | Checkbox buried in settings | Toggle at top |
| Add rate | Navigate to Tax tab → Add rate → Fill form | Predefined + one-click add |
| Multi-country | Manual for each | Smart suggestions |
| Learning curve | 30 minutes | 30 seconds |

---

## Next Steps

1. Create Tax settings page component
2. Build backend API endpoints
3. Add predefined rates data
4. Test with Indonesian store
5. Test with multi-country store