docs: Update all documentation for standalone mode and settings structure

2025-11-05 11:28:09 +07:00
parent 3e7d75c98c
commit d52fc3bb24
6 changed files with 271 additions and 33 deletions
--- 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
--- 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 |

--- 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.):

--- 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
--- 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
--- 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 ? [
+      get children() {
+        const isStandalone = (window as any).WNW_CONFIG?.standaloneMode;
+        if (!isStandalone) return [];
+        
+        return [
          // WooNooW Settings
-        { label: 'WooNooW', mode: 'spa', path: '/settings' },
+          { label: 'WooNooW', mode: 'spa' as const, path: '/settings' },
          
          // 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' },
+          { 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', 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` },
-      ] : [],
+          { 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` },
+        ];
+      },
    },
  ];
 }