From d52fc3bb2428c84e4356df2ae2bb761837231ee5 Mon Sep 17 00:00:00 2001 From: dwindown Date: Wed, 5 Nov 2025 11:28:09 +0700 Subject: [PATCH] docs: Update all documentation for standalone mode and settings structure --- PROGRESS_NOTE.md | 163 ++++++++++++++++++++++++++++++++++++++ PROJECT_BRIEF.md | 2 +- PROJECT_SOP.md | 64 ++++++++++++++- README.md | 5 ++ SPA_ADMIN_MENU_PLAN.md | 29 ++++--- admin-spa/src/nav/tree.ts | 41 +++++----- 6 files changed, 271 insertions(+), 33 deletions(-) diff --git a/PROGRESS_NOTE.md b/PROGRESS_NOTE.md index 715d7f9..7cdce80 100644 --- a/PROGRESS_NOTE.md +++ b/PROGRESS_NOTE.md @@ -2062,3 +2062,166 @@ All endpoints support caching (5 minutes): **Total Development Time:** ~6 hours **Status:** βœ… Production Ready **Next Milestone:** Products module OR Settings module + +--- + +## πŸš€ Standalone Admin Mode β€” November 5, 2025 + +### βœ… COMPLETE - Three Admin Modes Implemented + +**Goal:** Provide flexible admin interface access with three distinct modes: normal (wp-admin), fullscreen, and standalone. + +### 🎯 Three Admin Modes + +#### **1. Normal Mode (wp-admin)** +- **URL:** `/wp-admin/admin.php?page=woonoow` +- **Layout:** WordPress admin sidebar + WooNooW SPA +- **Use Case:** Traditional WordPress admin workflow +- **Features:** + - WordPress admin bar visible + - WordPress sidebar navigation + - WooNooW SPA in main content area + - Settings submenu hidden (use WooCommerce settings) + +#### **2. Fullscreen Mode** +- **Toggle:** Fullscreen button in header +- **Layout:** WooNooW SPA only (no WordPress chrome) +- **Use Case:** Focus mode for order processing +- **Features:** + - Maximized workspace + - Distraction-free interface + - All WooNooW features accessible + - Settings submenu hidden + +#### **3. Standalone Mode** ✨ NEW +- **URL:** `https://yoursite.com/admin` +- **Layout:** Complete standalone application +- **Use Case:** Quick daily access, mobile-friendly +- **Features:** + - Custom login page (`/admin#/login`) + - WordPress authentication integration + - Settings submenu visible (SPA settings pages) + - "WordPress" button to access wp-admin + - "Logout" button in header + - Admin bar link in wp-admin to standalone + +### πŸ”§ Implementation Details + +#### **Backend Changes** + +**File:** `includes/Admin/StandaloneAdmin.php` +- Handles `/admin` and `/admin/` requests +- Renders standalone HTML template +- Localizes `WNW_CONFIG` with `standaloneMode: true` +- Provides authentication state +- Includes store settings (currency, formatting) + +**File:** `includes/Admin/Menu.php` +- Added admin bar link to standalone mode +- Icon: `dashicons-store` +- Only visible to users with `manage_woocommerce` capability + +**File:** `includes/Api/AuthController.php` +- Login endpoint using native WordPress authentication +- Sequence: `wp_authenticate()` β†’ `wp_clear_auth_cookie()` β†’ `wp_set_current_user()` β†’ `wp_set_auth_cookie()` β†’ `do_action('wp_login')` +- Ensures session persistence between standalone and wp-admin + +#### **Frontend Changes** + +**File:** `admin-spa/src/App.tsx` +- `AuthWrapper` component handles authentication +- Login/logout flow with page reload +- "WordPress" button in header (standalone only) +- "Logout" button in header (standalone only) + +**File:** `admin-spa/src/routes/Login.tsx` +- Custom login form +- Username/password authentication +- Redirects to dashboard after login +- Page reload to pick up fresh cookies/nonces + +**File:** `admin-spa/src/nav/tree.ts` +- Dynamic settings submenu using getter +- Only shows in standalone mode: `get children() { return isStandalone ? [...] : [] }` +- Dashboard path: `/dashboard` (with redirect from `/`) + +### πŸ“Š Navigation Structure + +**Standalone Mode Settings:** +``` +Settings +β”œβ”€β”€ WooNooW (main settings) +β”œβ”€β”€ General (store settings) +β”œβ”€β”€ Payments (gateways) +β”œβ”€β”€ Shipping (zones, methods) +β”œβ”€β”€ Products (inventory) +β”œβ”€β”€ Tax (rates) +β”œβ”€β”€ Accounts & Privacy +β”œβ”€β”€ Emails (templates) +β”œβ”€β”€ Advanced (bridge to wp-admin) +β”œβ”€β”€ Integration (bridge to wp-admin) +β”œβ”€β”€ Status (bridge to wp-admin) +└── Extensions (bridge to wp-admin) +``` + +**Strategy:** Option A - Everyday Use Dashboard +- Focus on most-used settings +- Bridge to wp-admin for advanced settings +- Extensible for 3rd party plugins +- Coexist with WooCommerce + +### πŸ” Authentication Flow + +**Standalone Login:** +1. User visits `/admin` +2. Not authenticated β†’ redirect to `/admin#/login` +3. Submit credentials β†’ `POST /wp-json/woonoow/v1/auth/login` +4. Backend sets WordPress auth cookies +5. Page reload β†’ authenticated state +6. Access all WooNooW features + +**Session Persistence:** +- Login in standalone β†’ logged in wp-admin βœ… +- Login in wp-admin β†’ logged in standalone βœ… +- Logout in standalone β†’ logged out wp-admin βœ… +- Logout in wp-admin β†’ logged out standalone βœ… + +### πŸ“± Cross-Navigation + +**From Standalone to wp-admin:** +- Click "WordPress" button in header +- Opens `/wp-admin` in same tab +- Session persists + +**From wp-admin to Standalone:** +- Click "WooNooW" in admin bar +- Opens `/admin` in same tab +- Session persists + +### βœ… Features Completed + +- [x] Standalone mode routing (`/admin`) +- [x] Custom login page +- [x] WordPress authentication integration +- [x] Session persistence +- [x] Settings submenu (standalone only) +- [x] WordPress button in header +- [x] Logout button in header +- [x] Admin bar link to standalone +- [x] Dashboard path consistency (`/dashboard`) +- [x] Dynamic navigation tree +- [x] Settings placeholder pages +- [x] Documentation updates + +### πŸ“š Documentation + +- `STANDALONE_ADMIN_SETUP.md` - Setup guide +- `PROJECT_BRIEF.md` - Updated Phase 4 +- `PROJECT_SOP.md` - Section 7 (modes explanation) +- `PROGRESS_NOTE.md` - This section + +--- + +**Implementation Date:** November 5, 2025 +**Status:** βœ… Production Ready +**Next Milestone:** Implement General/Payments/Shipping settings pages diff --git a/PROJECT_BRIEF.md b/PROJECT_BRIEF.md index 1e98a44..9f67153 100644 --- a/PROJECT_BRIEF.md +++ b/PROJECT_BRIEF.md @@ -41,7 +41,7 @@ By overlaying a fast React‑powered frontend and a modern admin SPA, WooNooW up | **Phase 1** | Core plugin foundation, menu, REST routes, async email | Working prototype with dashboard & REST health check | | **Phase 2** | Checkout Fast‑Path (quote, submit), cart hybrid SPA | Fast checkout pipeline, HPOS datastore | | **Phase 3** | Customer SPA (My Account, Orders, Addresses) | React SPA integrated with Woo REST | -| **Phase 4** | Admin SPA (Orders List, Detail, Dashboard) | React admin interface replacing Woo Admin | +| **Phase 4** | Admin SPA (Orders List, Detail, Dashboard, Standalone Mode) | React admin interface with 3 modes: normal (wp-admin), fullscreen, standalone | | **Phase 5** | Compatibility Hooks & Slots | Legacy addon support maintained | | **Phase 6** | Packaging & Licensing | Release build, Sejoli integration, and addon manager | diff --git a/PROJECT_SOP.md b/PROJECT_SOP.md index 97c9653..7e1bb2f 100644 --- a/PROJECT_SOP.md +++ b/PROJECT_SOP.md @@ -857,7 +857,69 @@ Use Orders as the template for building new core modules. --- -## 7. πŸ€– AI Agent Collaboration Rules +## 7. 🎨 Admin Interface Modes + +WooNooW provides **three distinct admin interface modes** to accommodate different workflows and user preferences: + +### **1. Normal Mode (wp-admin)** +- **Access:** `/wp-admin/admin.php?page=woonoow` +- **Layout:** Traditional WordPress admin with WooNooW SPA in content area +- **Use Case:** Standard WordPress admin workflow +- **Features:** + - WordPress admin bar and sidebar visible + - Full WordPress admin functionality + - WooNooW SPA integrated seamlessly + - Settings submenu hidden (use WooCommerce settings) +- **When to use:** When you need access to other WordPress admin features alongside WooNooW + +### **2. Fullscreen Mode** +- **Access:** Toggle button in WooNooW header +- **Layout:** WooNooW SPA only (no WordPress chrome) +- **Use Case:** Focused work sessions, order processing +- **Features:** + - Maximized workspace + - Distraction-free interface + - All WooNooW features accessible + - Settings submenu hidden +- **When to use:** When you want to focus exclusively on WooNooW tasks + +### **3. Standalone Mode** ✨ +- **Access:** `https://yoursite.com/admin` +- **Layout:** Complete standalone application with custom login +- **Use Case:** Quick daily access, mobile-friendly, bookmark-able +- **Features:** + - Custom login page (`/admin#/login`) + - WordPress authentication integration + - Settings submenu visible (SPA settings pages) + - "WordPress" button to access wp-admin + - "Logout" button in header + - Admin bar link in wp-admin to standalone + - Session persistence across modes +- **When to use:** As your primary WooNooW interface, especially on mobile or for quick access + +### **Mode Switching** +- **From wp-admin to Standalone:** Click "WooNooW" in admin bar +- **From Standalone to wp-admin:** Click "WordPress" button in header +- **To Fullscreen:** Click fullscreen toggle in any mode +- **Session persistence:** Login state is shared across all modes + +### **Settings Submenu Behavior** +- **Normal Mode:** No settings submenu (use WooCommerce settings in wp-admin) +- **Fullscreen Mode:** No settings submenu +- **Standalone Mode:** Full settings submenu visible with SPA pages + +**Implementation:** Settings submenu uses dynamic getter in `admin-spa/src/nav/tree.ts`: +```typescript +get children() { + const isStandalone = (window as any).WNW_CONFIG?.standaloneMode; + if (!isStandalone) return []; + return [ /* settings items */ ]; +} +``` + +--- + +## 8. πŸ€– AI Agent Collaboration Rules When using an AI IDE agent (ChatGPT, Claude, etc.): diff --git a/README.md b/README.md index 791a1eb..ec0b695 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,11 @@ **WooNooW** is a modern experience layer for WooCommerce β€” enhancing UX, speed, and reliability **without data migration**. It keeps WooCommerce as the core engine while providing a modern React-powered interface for both the **storefront** (cart, checkout, my‑account) and the **admin** (orders, dashboard). +**Three Admin Modes:** +- **Normal Mode:** Traditional wp-admin integration (`/wp-admin/admin.php?page=woonoow`) +- **Fullscreen Mode:** Distraction-free interface (toggle in header) +- **Standalone Mode:** Complete standalone app at `yoursite.com/admin` with custom login ✨ + --- ## πŸ” Background diff --git a/SPA_ADMIN_MENU_PLAN.md b/SPA_ADMIN_MENU_PLAN.md index d07a257..f9743ac 100644 --- a/SPA_ADMIN_MENU_PLAN.md +++ b/SPA_ADMIN_MENU_PLAN.md @@ -182,7 +182,9 @@ Marketing ## Proposed SPA Main Menu (Authoritative) -This replaces wp‑admin’s structure with a focused SPA hierarchy. Analytics & Marketing are folded into **Dashboard**. **Status** and **Extensions** live under **Settings**. +This replaces wp‑admin's structure with a focused SPA hierarchy. Analytics & Marketing are folded into **Dashboard**. **Status** and **Extensions** live under **Settings**. + +**Note:** Settings submenu is **only visible in Standalone Mode** (`/admin`). In normal wp-admin mode, users access WooCommerce settings through the standard WordPress admin interface. ```text Dashboard @@ -214,18 +216,19 @@ Customers └── All Customers (/customers) (Customers are derived from orders + user profiles; non‑buyers are excluded by default.) -Settings -β”œβ”€β”€ General (/settings/general) -β”œβ”€β”€ Products (/settings/products) -β”œβ”€β”€ Tax (/settings/tax) -β”œβ”€β”€ Shipping (/settings/shipping) -β”œβ”€β”€ Payments (/settings/payments) -β”œβ”€β”€ Accounts & Privacy (/settings/accounts) -β”œβ”€β”€ Emails (/settings/emails) -β”œβ”€β”€ Integrations (/settings/integrations) -β”œβ”€β”€ Advanced (/settings/advanced) -β”œβ”€β”€ Status (/settings/status) -└── Extensions (/settings/extensions) +Settings (Standalone Mode Only) +β”œβ”€β”€ WooNooW (/settings) ← plugin settings +β”œβ”€β”€ General (/settings/general) ← SPA +β”œβ”€β”€ Payments (/settings/payments) ← SPA +β”œβ”€β”€ Shipping (/settings/shipping) ← SPA +β”œβ”€β”€ Products (/settings/products) ← SPA +β”œβ”€β”€ Tax (/settings/tax) ← SPA +β”œβ”€β”€ Accounts & Privacy (/settings/accounts) ← SPA +β”œβ”€β”€ Emails (/settings/emails) ← SPA +β”œβ”€β”€ Advanced (bridge to wp-admin) ← Bridge +β”œβ”€β”€ Integration (bridge to wp-admin) ← Bridge +β”œβ”€β”€ Status (bridge to wp-admin) ← Bridge +└── Extensions (bridge to wp-admin) ← Bridge ``` ### Routing notes diff --git a/admin-spa/src/nav/tree.ts b/admin-spa/src/nav/tree.ts index fb00c4c..83efb79 100644 --- a/admin-spa/src/nav/tree.ts +++ b/admin-spa/src/nav/tree.ts @@ -103,25 +103,30 @@ function getStaticFallbackTree(): MainNode[] { path: '/settings', icon: 'settings', // Only show submenu in standalone mode - children: (window as any).WNW_CONFIG?.standaloneMode ? [ - // WooNooW Settings - { label: 'WooNooW', mode: 'spa', path: '/settings' }, + get children() { + const isStandalone = (window as any).WNW_CONFIG?.standaloneMode; + if (!isStandalone) return []; - // WooCommerce Settings (Most Used First) - { label: 'General', mode: 'spa', path: '/settings/general' }, - { label: 'Payments', mode: 'spa', path: '/settings/payments' }, - { label: 'Shipping', mode: 'spa', path: '/settings/shipping' }, - { label: 'Products', mode: 'spa', path: '/settings/products' }, - { label: 'Tax', mode: 'spa', path: '/settings/tax' }, - { label: 'Accounts & Privacy', mode: 'spa', path: '/settings/accounts' }, - { label: 'Emails', mode: 'spa', path: '/settings/emails' }, - - // Less Common (Bridge to WP Admin for now) - { label: 'Advanced', mode: 'bridge', href: `${admin}?page=wc-settings&tab=advanced` }, - { label: 'Integration', mode: 'bridge', href: `${admin}?page=wc-settings&tab=integration` }, - { label: 'Status', mode: 'bridge', href: `${admin}?page=wc-status` }, - { label: 'Extensions', mode: 'bridge', href: `${admin}?page=wc-addons` }, - ] : [], + return [ + // WooNooW Settings + { label: 'WooNooW', mode: 'spa' as const, path: '/settings' }, + + // WooCommerce Settings (Most Used First) + { label: 'General', mode: 'spa' as const, path: '/settings/general' }, + { label: 'Payments', mode: 'spa' as const, path: '/settings/payments' }, + { label: 'Shipping', mode: 'spa' as const, path: '/settings/shipping' }, + { label: 'Products', mode: 'spa' as const, path: '/settings/products' }, + { label: 'Tax', mode: 'spa' as const, path: '/settings/tax' }, + { label: 'Accounts & Privacy', mode: 'spa' as const, path: '/settings/accounts' }, + { label: 'Emails', mode: 'spa' as const, path: '/settings/emails' }, + + // Less Common (Bridge to WP Admin for now) + { label: 'Advanced', mode: 'bridge' as const, href: `${admin}?page=wc-settings&tab=advanced` }, + { label: 'Integration', mode: 'bridge' as const, href: `${admin}?page=wc-settings&tab=integration` }, + { label: 'Status', mode: 'bridge' as const, href: `${admin}?page=wc-status` }, + { label: 'Extensions', mode: 'bridge' as const, href: `${admin}?page=wc-addons` }, + ]; + }, }, ]; }