diff --git a/SETTINGS_TREE_PLAN.md b/SETTINGS_TREE_PLAN.md new file mode 100644 index 0000000..efe0398 --- /dev/null +++ b/SETTINGS_TREE_PLAN.md @@ -0,0 +1,550 @@ +# WooNooW Settings Tree - Implementation Plan + +## ๐Ÿ“‹ Overview + +This document defines the complete settings structure for WooNooW Admin SPA, including what needs to be built, priorities, and implementation approach. + +--- + +## ๐ŸŽฏ Strategy: Option A - Everyday Use Dashboard + +**Philosophy:** +- Focus on most-used settings (80/20 rule) +- Bridge to wp-admin for advanced/rarely-used features +- Extensible for 3rd party plugins +- Coexist with WooCommerce (no replacement) + +--- + +## ๐ŸŒฒ Settings Tree Structure + +``` +Settings +โ”œโ”€โ”€ ๐Ÿ”ง WooNooW (Plugin Settings) +โ”‚ โ””โ”€โ”€ /settings +โ”‚ +โ”œโ”€โ”€ ๐Ÿช General (Store Settings) +โ”‚ โ””โ”€โ”€ /settings/general +โ”‚ +โ”œโ”€โ”€ ๐Ÿ’ณ Payments (Payment Gateways) +โ”‚ โ””โ”€โ”€ /settings/payments +โ”‚ +โ”œโ”€โ”€ ๐Ÿ“ฆ Shipping (Zones & Methods) +โ”‚ โ””โ”€โ”€ /settings/shipping +โ”‚ +โ”œโ”€โ”€ ๐Ÿ“ฆ Products (Inventory & Downloads) +โ”‚ โ””โ”€โ”€ /settings/products +โ”‚ +โ”œโ”€โ”€ ๐Ÿ’ฐ Tax (Tax Rates & Classes) +โ”‚ โ””โ”€โ”€ /settings/tax +โ”‚ +โ”œโ”€โ”€ ๐Ÿ‘ค Accounts & Privacy +โ”‚ โ””โ”€โ”€ /settings/accounts +โ”‚ +โ”œโ”€โ”€ ๐Ÿ“ง Emails (Templates & Settings) +โ”‚ โ””โ”€โ”€ /settings/emails +โ”‚ +โ”œโ”€โ”€ โš™๏ธ Advanced (Bridge to wp-admin) +โ”‚ โ””โ”€โ”€ /wp-admin/admin.php?page=wc-settings&tab=advanced +โ”‚ +โ”œโ”€โ”€ ๐Ÿ”Œ Integration (Bridge to wp-admin) +โ”‚ โ””โ”€โ”€ /wp-admin/admin.php?page=wc-settings&tab=integration +โ”‚ +โ”œโ”€โ”€ ๐Ÿ” Status (System Status) +โ”‚ โ””โ”€โ”€ /wp-admin/admin.php?page=wc-status +โ”‚ +โ””โ”€โ”€ ๐Ÿงฉ Extensions (Marketplace) + โ””โ”€โ”€ /wp-admin/admin.php?page=wc-addons +``` + +--- + +## ๐Ÿ“Š Implementation Priority + +### **Phase 1: Core Settings (HIGH PRIORITY)** ๐Ÿ”ด + +#### 1. General Settings (`/settings/general`) +**Purpose:** Store address, currency, units +**Complexity:** Medium +**Estimated Time:** 4-6 hours + +**Fields:** +- Store Address (address 1, address 2, city, country, state, postcode) +- Selling Location (sell to all countries, specific countries) +- Shipping Location (ship to all countries, specific countries, disable shipping) +- Default Customer Location (shop country, geolocate, no location by default) +- Currency (currency, position, thousand separator, decimal separator, decimals) +- API Settings (REST API enabled) + +**UI Components:** +- Text inputs +- Country/State selectors +- Currency selector +- Radio groups +- Checkboxes + +--- + +#### 2. Payment Settings (`/settings/payments`) +**Purpose:** Enable/disable payment gateways, configure settings +**Complexity:** Medium-High +**Estimated Time:** 6-8 hours + +**Features:** +- List all available payment gateways +- Enable/disable toggle for each gateway +- Gateway-specific settings (expandable panels) +- Drag-and-drop ordering +- Test mode indicators + +**UI Components:** +- Sortable list +- Toggle switches +- Expandable panels (accordion) +- Gateway-specific forms (dynamic based on gateway) + +**Gateways to Support:** +- Direct Bank Transfer (BACS) +- Check Payments +- Cash on Delivery +- PayPal (if installed) +- Stripe (if installed) +- Other 3rd party gateways (extensible) + +--- + +#### 3. Shipping Settings (`/settings/shipping`) +**Purpose:** Shipping zones, methods, and classes +**Complexity:** High +**Estimated Time:** 8-12 hours + +**Features:** +- **Shipping Zones:** + - List all zones + - Add/edit/delete zones + - Zone regions (countries, states, postcodes) + - Zone methods (flat rate, free shipping, local pickup) + +- **Shipping Classes:** + - List all classes + - Add/edit/delete classes + - Class descriptions + +- **Shipping Options:** + - Enable/disable shipping calculator + - Hide shipping costs until address entered + - Debug mode + +**UI Components:** +- Zone list with drag-and-drop +- Region selector (multi-select countries/states) +- Method configuration forms +- Shipping class manager +- Cost calculator inputs + +--- + +### **Phase 2: Product & Customer Settings (MEDIUM PRIORITY)** ๐ŸŸก + +#### 4. Product Settings (`/settings/products`) +**Purpose:** Shop page, inventory, downloadable products +**Complexity:** Medium +**Estimated Time:** 4-6 hours + +**Sections:** +- **General:** + - Shop page + - Add to cart behavior + - Placeholder images + +- **Inventory:** + - Manage stock + - Hold stock (minutes) + - Notifications (low stock, out of stock) + - Low stock threshold + - Out of stock threshold + - Hide out of stock items + +- **Downloadable Products:** + - File download method + - Access restriction + - Grant access after payment + +**UI Components:** +- Page selectors +- Number inputs +- Checkboxes +- Radio groups +- Select dropdowns + +--- + +#### 5. Tax Settings (`/settings/tax`) +**Purpose:** Tax rates, classes, and options +**Complexity:** Medium-High +**Estimated Time:** 6-8 hours + +**Features:** +- **Tax Options:** + - Prices entered with tax + - Calculate tax based on (customer address, shop address) + - Shipping tax class + - Rounding + - Additional tax classes + +- **Standard Rates:** + - Country/State/Postcode + - Rate % + - Tax name + - Priority + - Compound + - Shipping + +- **Tax Classes:** + - List all classes + - Add/edit/delete classes + +**UI Components:** +- Tax rate table (sortable, editable) +- Country/State selectors +- Percentage inputs +- Checkbox groups +- Tax class manager + +--- + +#### 6. Accounts & Privacy (`/settings/accounts`) +**Purpose:** Guest checkout, account creation, privacy +**Complexity:** Low-Medium +**Estimated Time:** 3-4 hours + +**Sections:** +- **Guest Checkout:** + - Allow customers to place orders without account + - Allow customers to log in during checkout + +- **Account Creation:** + - Allow customers to create account during checkout + - Allow customers to create account on "My Account" page + - Automatically generate username + - Automatically generate password + +- **Privacy:** + - Privacy policy page + - Registration privacy policy text + - Checkout privacy policy text + - Remove personal data (retention period) + - Remove access to download (retention period) + +**UI Components:** +- Checkboxes +- Page selector +- Textarea for policy text +- Number inputs (retention periods) + +--- + +### **Phase 3: Communication (MEDIUM PRIORITY)** ๐ŸŸก + +#### 7. Email Settings (`/settings/emails`) +**Purpose:** Email templates and settings +**Complexity:** Medium-High +**Estimated Time:** 6-8 hours + +**Features:** +- **Email List:** + - New Order (admin) + - Cancelled Order (admin) + - Failed Order (admin) + - Order On-Hold (customer) + - Processing Order (customer) + - Completed Order (customer) + - Refunded Order (customer) + - Customer Invoice + - Customer Note + - Reset Password + - New Account + +- **Email Settings (per email):** + - Enable/disable + - Subject + - Heading + - Additional content + - Email type (plain text, HTML, multipart) + +- **Global Settings:** + - "From" name + - "From" email address + - Header image + - Footer text + - Base color + - Background color + - Body background color + - Body text color + +**UI Components:** +- Email list with enable/disable toggles +- Email editor (per email) +- Color pickers +- Image uploader +- Text inputs +- Textarea +- Email preview + +--- + +### **Phase 4: Advanced (KEEP IN WP-ADMIN)** โšช + +These settings are rarely used and can remain in wp-admin: + +#### 8. Advanced Settings (Bridge) +- Page setup (cart, checkout, my account, terms) +- REST API +- Webhooks +- Legacy API +- WooCommerce.com account + +#### 9. Integration Settings (Bridge) +- MaxMind Geolocation +- Other integrations + +#### 10. System Status (Bridge) +- System status report +- Tools (clear cache, regenerate thumbnails, etc.) +- Logs +- Scheduled actions + +#### 11. Extensions (Bridge) +- WooCommerce marketplace +- Browse extensions +- My subscriptions + +--- + +## ๐Ÿ”ง Technical Implementation + +### Backend (PHP) + +**Files to Create/Modify:** +1. `includes/Admin/Rest/SettingsController.php` - REST endpoints +2. `includes/Compat/SettingsProvider.php` - Settings data provider +3. `includes/Compat/NavigationRegistry.php` - โœ… Already updated + +**REST Endpoints:** +```php +GET /wp-json/woonoow/v1/settings/general +POST /wp-json/woonoow/v1/settings/general +GET /wp-json/woonoow/v1/settings/payments +POST /wp-json/woonoow/v1/settings/payments +GET /wp-json/woonoow/v1/settings/shipping +POST /wp-json/woonoow/v1/settings/shipping +// ... etc +``` + +**Data Flow:** +1. Frontend requests settings via REST API +2. Backend reads from WooCommerce options +3. Backend returns structured JSON +4. Frontend displays in form +5. User submits changes +6. Backend validates and saves to WooCommerce options +7. Frontend shows success/error + +--- + +### Frontend (React/TypeScript) + +**Files to Create:** +``` +admin-spa/src/routes/Settings/ +โ”œโ”€โ”€ index.tsx โœ… Done (WooNooW settings) +โ”œโ”€โ”€ General.tsx โœ… Placeholder created +โ”œโ”€โ”€ Payments.tsx โœ… Placeholder created +โ”œโ”€โ”€ Shipping.tsx โœ… Placeholder created +โ”œโ”€โ”€ Products.tsx โณ To create +โ”œโ”€โ”€ Tax.tsx โณ To create +โ”œโ”€โ”€ Accounts.tsx โณ To create +โ”œโ”€โ”€ Emails.tsx โณ To create +โ””โ”€โ”€ components/ + โ”œโ”€โ”€ SettingsForm.tsx โณ Reusable form component + โ”œโ”€โ”€ SettingsSection.tsx โณ Section wrapper + โ”œโ”€โ”€ SettingsField.tsx โณ Field renderer + โ”œโ”€โ”€ PaymentGatewayList.tsx โณ Payment gateway manager + โ”œโ”€โ”€ ShippingZoneList.tsx โณ Shipping zone manager + โ”œโ”€โ”€ TaxRateTable.tsx โณ Tax rate editor + โ””โ”€โ”€ EmailTemplateList.tsx โณ Email template manager +``` + +**Shared Components:** +- Form wrapper with save/cancel +- Field renderer (text, select, checkbox, radio, textarea, color, image) +- Section headers +- Help text/tooltips +- Validation messages +- Loading states +- Success/error notifications + +--- + +## ๐ŸŽจ UI/UX Guidelines + +### Layout +- Two-column layout on desktop (sidebar + content) +- Single column on mobile +- Sticky save button +- Breadcrumb navigation +- Section anchors (jump to section) + +### Forms +- Clear labels and help text +- Inline validation +- Required field indicators +- Default values shown +- Reset to defaults button +- Unsaved changes warning + +### Feedback +- Loading spinners during save +- Success toast notifications +- Error messages with details +- Confirmation dialogs for destructive actions + +### Accessibility +- Keyboard navigation +- Screen reader support +- Focus indicators +- ARIA labels +- Color contrast compliance + +--- + +## ๐Ÿ“ Implementation Checklist + +### Phase 1: Core Settings +- [ ] General Settings page + - [ ] Store address fields + - [ ] Currency settings + - [ ] Location settings + - [ ] Save/load functionality + - [ ] Validation + +- [ ] Payment Settings page + - [ ] Gateway list + - [ ] Enable/disable toggles + - [ ] Gateway configuration + - [ ] Drag-and-drop ordering + - [ ] Save/load functionality + +- [ ] Shipping Settings page + - [ ] Shipping zones list + - [ ] Zone editor + - [ ] Region selector + - [ ] Shipping methods + - [ ] Shipping classes + - [ ] Save/load functionality + +### Phase 2: Product & Customer Settings +- [ ] Product Settings page +- [ ] Tax Settings page +- [ ] Accounts & Privacy page + +### Phase 3: Communication +- [ ] Email Settings page + +--- + +## ๐Ÿงช Testing Requirements + +### Functional Testing +- [ ] All fields save correctly +- [ ] Validation works +- [ ] Default values load +- [ ] Changes persist after reload +- [ ] Bridge links work +- [ ] Mobile responsive + +### Integration Testing +- [ ] WooCommerce compatibility +- [ ] 3rd party gateway support +- [ ] Plugin conflict testing +- [ ] Multi-currency support + +### User Testing +- [ ] Intuitive navigation +- [ ] Clear labels +- [ ] Helpful error messages +- [ ] Fast performance + +--- + +## ๐Ÿ“š Documentation + +### User Documentation +- Settings overview +- Field descriptions +- Common configurations +- Troubleshooting + +### Developer Documentation +- API endpoints +- Filter hooks +- Extension points +- Code examples + +--- + +## ๐Ÿ”„ Migration Notes + +**No data migration needed!** +- All settings use WooCommerce's native options +- Deactivating WooNooW restores wp-admin settings +- No data loss risk + +--- + +## ๐ŸŽฏ Success Metrics + +### Phase 1 Complete When: +- โœ… General, Payments, Shipping pages functional +- โœ… All fields save/load correctly +- โœ… Mobile responsive +- โœ… No console errors +- โœ… User testing passed + +### Phase 2 Complete When: +- โœ… Products, Tax, Accounts pages functional +- โœ… All validations working +- โœ… Performance acceptable (<2s load) + +### Phase 3 Complete When: +- โœ… Email settings functional +- โœ… Email preview working +- โœ… Template customization working + +--- + +## ๐Ÿ“… Timeline Estimate + +| Phase | Pages | Estimated Time | Priority | +|-------|-------|----------------|----------| +| Phase 1 | General, Payments, Shipping | 18-26 hours | ๐Ÿ”ด HIGH | +| Phase 2 | Products, Tax, Accounts | 13-18 hours | ๐ŸŸก MEDIUM | +| Phase 3 | Emails | 6-8 hours | ๐ŸŸก MEDIUM | +| **Total** | **7 pages** | **37-52 hours** | | + +**Note:** Times include design, implementation, testing, and documentation. + +--- + +## ๐Ÿ”— Related Documents + +- `PROGRESS_NOTE.md` - Development progress +- `SPA_ADMIN_MENU_PLAN.md` - Menu structure +- `PROJECT_SOP.md` - Development standards +- `STANDALONE_MODE_SUMMARY.md` - Mode documentation + +--- + +**Last Updated:** November 5, 2025 +**Status:** ๐Ÿ“‹ Planning Complete, Ready for Implementation +**Next Step:** Implement Phase 1 - General Settings