rspade_system/app/RSpade/Core/SPA/CLAUDE.md

RSpade Spa System

Overview

The RSpade Spa system enables client-side routing for authenticated areas of applications using the JQHTML component framework.

Core Classes

Spa_Action

Base class for Spa pages/routes. Each action represents a distinct page in the application.

Example:

class Users_View_Action extends Spa_Action {
    static route = '/users/:user_id';
    static layout = 'Frontend_Layout';

    on_create() {
        console.log(this.args.user_id); // URL parameter from route
    }
}

Spa_Layout

Persistent wrapper component containing navigation, header, footer, etc. Layouts have a content area where actions render.

Example:

class Frontend_Layout extends Spa_Layout {
    on_create() {
        // Initialize layout structure
        // Create navigation, header, footer
        // Define content area for actions
    }
}

Spa

Main Spa application class that initializes the router and manages navigation between actions.

Spa_Router

Core routing engine adapted from JQHTML framework. Handles URL matching, parameter extraction, and navigation.

Discovery

Spa actions are discovered during manifest build using:

Manifest::is_js_subclass_of('Spa_Action')

No filename conventions required - any class extending Spa_Action is automatically registered.

URL Generation

PHP:

$url = Rsx::SpaRoute('Users_View_Action', ['user_id' => 123]);
// Returns: "/users/123"

JavaScript:

const url = Rsx.SpaRoute('Users_View_Action', {user_id: 123, tab: 'posts'});
// Returns: "/users/123?tab=posts"

Architecture

Bootstrap Flow

1. User requests Spa route (e.g., /users/123)
2. Dispatcher detects Spa route in manifest
3. Server renders spa_bootstrap.blade.php with bundle
4. Client initializes Spa application
5. Router matches URL to action
6. Layout renders with action inside

Navigation Flow

1. User clicks link or calls Rsx.SpaRoute()
2. Router matches URL to action class
3. Current action destroyed (if exists)
4. New action instantiated with URL parameters
5. Action renders within persistent layout
6. Browser history updated

Implementation Status

Phase 1: Foundation Setup - ✅ COMPLETE

• Directory structure created
• Placeholder files in place
• Router code copied from JQHTML export

Phase 2+: See /var/www/html/docs.dev/Spa_INTEGRATION_PLAN.md

Directory Structure

/system/app/RSpade/Core/Jqhtml_Spa/
├── CLAUDE.md                        # This file
├── Spa_Bootstrap.php                # Server-side bootstrap handler
├── Spa_Parser.php                   # Parse JS files for action metadata
├── Spa_Manifest.php                 # Manifest integration helper
├── spa_bootstrap.blade.php          # Bootstrap blade layout
├── Spa_Router.js                 # Core router (from JQHTML)
├── Spa.js                           # Spa application base class
├── Spa_Layout.js                    # Layout base class
└── Spa_Action.js                    # Action base class

Notes

• Spa routes are auth-only (no SEO concerns)
• Server does not render Spa pages (client-side only)
• Actions live alongside PHP controllers in feature directories
• Controllers provide Ajax endpoints, actions provide UI
• Layouts persist across action navigation (no re-render)
• Component renamed from Component to Component (legacy alias maintained)