formipay/MIGRATION_STRATEGY.md

# Formipay — Vue to React Migration Strategy

**Date:** April 18, 2026
**Context:** Phase 2 — React Admin Foundation

---

## Overview

This document explains how to approach the existing Vue.js code in Formipay during the migration to React admin panels.

**Key Principle:** We are NOT doing a "rewrite everything at once" approach. Vue and React will coexist during Phase 2, with Vue being removed incrementally as React replacements are shipped.

---

## Current Vue.js Usage Inventory

| Type | Location | Purpose | Replacement Phase |
|------|----------|---------|-------------------|
| **WPCFTO Framework** | `vendor/` | Settings form builder (repeater, fields, etc.) | F2.8 (Global Settings) |
| **Custom Vue 2 App** | `admin/assets/js/admin-product-editor.js` | Product variation pricing table | F2.9 (Product Editor) |
| **Partial Vue Editor** | `admin/assets/vue/` (if exists) | Form builder canvas | F2.4 (Form Builder) |

---

## Migration Strategy

### Phase 1: Coexistence (Current State)

```
┌─────────────────────────────────────────────┐
│  Admin Pages                                  │
├─────────────────────────────────────────────┤
│  Forms     │ Products  │ Orders │ Settings    │
│  WPCFTO    │ WPCFTO    │ WPCFTO  │ WPCFTO       │
│  + Vue     │ + Vue     │ (none)  │ + Vue        │
│            │ (custom)  │         │              │
└─────────────────────────────────────────────┘
```

**Status:** All pages working. WPCFTO handles forms, custom Vue handles product variations.

---

### Phase 2: Incremental React Rollout

**Week 3:** Build pipeline + React infrastructure. Vue untouched.

**Week 4:** React Form Builder replaces WPCFTO form editor.
```
Forms: WPCFTO/Vue → React ✅
Products: WPCFTO + custom Vue → unchanged
Orders: (none) → React ✅
Settings: WPCFTO → unchanged
```

**Week 5:** React Order Management (no Vue to touch).
```
Orders → React ✅
```

**Week 6:** React Global Settings replaces WPCFTO.
```
Settings: WPCFTO → React ✅
Products: WPCFTO + custom Vue → unchanged
```

**After Week 6:** WPCFTO framework can be fully removed. Only custom Vue remains.

---

### Product Editor Migration (F2.9)

The custom Vue app in `admin-product-editor.js` is the last Vue piece to migrate.

#### Current Features (Must Recreate in React)

| Feature | Complexity | Notes |
|---------|-----------|-------|
| Multi-currency flat pricing | Medium | Show all currencies as columns when enabled |
| Multi-currency expanded mode | High | Inner tables per variation row |
| Dynamic rows from attribute repeater | High | Syncs with WPCFTO repeater in real-time |
| Decimal digits per currency | Medium | Step values calculated from currency config |
| Required field validation | Low | Default currency must have price |
| Real-time JSON update to hidden input | Medium | `product_variation_variables` hidden field |
| SweetAlert2 error dialogs | Low | Uses existing window.Swal or custom alert |

#### Implementation Approach

**Option A: Recreate from Scratch (Recommended)**

1. **Read current Vue code logic** — understand the data flow
2. **Build React component** — `VariationPricingTable.jsx`
   - Use `@tanstack/react-table` for the table
   - Use `@wordpress/components` for form inputs (TextControl, etc.)
   - State management via React hooks (useState, useEffect)
3. **Data sync layer** — same API endpoint `get_product_variables`
4. **Validation logic** — port `findFirstMissingDefault()` to React

**Pros:** Clean React code, modern patterns, better type safety  
**Cons:** Requires careful testing to match all edge cases

**Option B: Vue-in-React Wrapper (Not Recommended)**

Wrap the existing Vue app in a React component using a library like `vue-react-wrapper`.

**Pros:** Faster, less risky  
**Cons:** Technical debt, adds bundle size, mixing paradigms

**Recommendation:** Option A — rewrite in React. The logic is well-contained (~500 lines) and rewriting gives us clean, maintainable React code.

---

## Migration Checklist for F2.9

When implementing the React Product Editor:

- [ ] Read and document current Vue variation table behavior
- [ ] Create `src/admin/pages/Products/VariationPricingTable.jsx`
- [ ] Implement multi-currency flat pricing mode
- [ ] Implement multi-currency expanded mode (inner tables)
- [ ] Implement attribute repeater sync (MutationObserver or polling)
- [ ] Implement decimal digits per currency step calculation
- [ ] Implement required field validation (default currency)
- [ ] Implement real-time JSON update to hidden `product_variation_variables` input
- [ ] Add SweetAlert2 or equivalent for validation errors
- [ ] Test with various currency configurations
- [ ] Test with existing products (data migration)
- [ ] Remove old Vue script enqueuing from Product page
- [ ] Remove Vue dependency if no longer used elsewhere

---

## Data Compatibility

The React component must read/write the same data format as the Vue app:

**Hidden input format** (`product_variation_variables`):
```json
[
  {
    "key": "Red|||Large",
    "name": "Red - Large",
    "stock": "",
    "weight": 0,
    "active": true,
    "prices": [
      {
        "currency": "USD:::United States Dollar:::$",
        "regular_price": "29.99",
        "sale_price": "24.99",
        "currency_decimal_digits": 2
      }
    ]
  }
]
```

**API endpoint** (already exists):
```php
// Product.php - add this if not present
add_action('wp_ajax_get_product_variables', [$this, 'ajax_get_product_variables']);
```

---

## Testing Strategy

1. **Unit Tests:** Test variation price calculation logic in isolation
2. **Integration Tests:** Test loading/saving variations via AJAX
3. **Manual Tests:**
   - Create product with variations
   - Test multi-currency flat mode
   - Test multi-currency expanded mode
   - Test validation (missing default price)
   - Test attribute repeater sync
   - Test editing existing products (data compatibility)

---

## Rollback Plan

If React version has critical bugs:
1. Keep Vue version as fallback
2. Add feature flag in settings: "Use React Product Editor (beta)"
3. Default to Vue, allow opting into React
4. Fix React, then make it default

---

## Notes

- **No Vue Router used** — the Vue app is a simple mount, no routing to worry about
- **No Vuex** — state is local component state + hidden input sync
- **jQuery dependency** — the Vue app uses jQuery for DOM selection (`$('#product-variables-table')`. React version should eliminate this.
- **Timing:** WPCFTO removal happens after Global Settings (F2.8), but Product Editor Vue app is independent — can be migrated anytime after Week 3.

---

*End of Migration Strategy.*