1b46c5270c
Add form value persistence across cache revalidation re-renders 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1315 lines
43 KiB
Markdown
Executable File
1315 lines
43 KiB
Markdown
Executable File
# RSpade Framework - AI/LLM Development Guide
|
|
|
|
**PURPOSE**: Essential directives for AI/LLM assistants developing RSX applications with RSpade.
|
|
|
|
## CRITICAL: Questions vs Commands
|
|
|
|
- **Questions get answers, NOT actions** - "Is that fire?" gets "Yes" not "Let me run through it". User has a plan, don't take destructive action when asked a question.
|
|
- **Commands get implementation** - Clear directives result in code changes
|
|
|
|
## What is RSpade?
|
|
|
|
**Visual Basic-like development for PHP/Laravel.** Think: VB6 apps → VB6 runtime → Windows = RSX apps → RSpade runtime → Laravel.
|
|
|
|
**Philosophy**: RSpade is rebellion against JavaScript fatigue. Like VB6 made Windows programming accessible, RSpade makes web development simple again. No build steps, no config hell, just code and reload.
|
|
|
|
**Important**: RSpade is built on Laravel but diverges significantly. Do not assume Laravel patterns work in RSX without verification.
|
|
|
|
**Terminology**: **RSpade** = Complete framework | **RSX** = Your application code in `/rsx/`
|
|
|
|
---
|
|
|
|
## CRITICAL RULES
|
|
|
|
### CRITICAL: RSpade Builds Automatically - NEVER RUN BUILD COMMANDS
|
|
|
|
**RSpade is INTERPRETED** - changes compile on-the-fly. NO manual build steps.
|
|
|
|
**FORBIDDEN** (unless explicitly instructed):
|
|
- `npm run compile/build` - Don't exist
|
|
- `bin/publish` - For releases, not testing
|
|
- `rsx:bundle:compile` / `rsx:manifest:build` / `rsx:clean` - Automatic
|
|
- ANY "build", "compile", or "publish" command
|
|
|
|
Edit → Save → Refresh browser → Changes live (< 1 second)
|
|
|
|
### Framework Updates
|
|
|
|
```bash
|
|
php artisan rsx:framework:pull # User-initiated only
|
|
```
|
|
|
|
### Fail Loud - No Silent Fallbacks
|
|
|
|
**ALWAYS fail visibly.** No redundant fallbacks, silent failures, or alternative code paths.
|
|
|
|
```php
|
|
// ❌ WRONG
|
|
try { $clean = Sanitizer::sanitize($input); }
|
|
catch (Exception $e) { $clean = $input; } // DISASTER
|
|
|
|
// ✅ CORRECT
|
|
$clean = Sanitizer::sanitize($input); // Let it throw
|
|
```
|
|
|
|
**SECURITY-CRITICAL**: Never continue after security failures. Only catch expected failures (file uploads, APIs, user input). Let exceptions bubble to global handler.
|
|
|
|
### No Defensive Coding
|
|
|
|
Core classes ALWAYS exist. Never check.
|
|
|
|
```javascript
|
|
// ❌ BAD: if (typeof Rsx !== 'undefined') { Rsx.Route('Controller::method') }
|
|
// ✅ GOOD: Rsx.Route('Controller::method')
|
|
```
|
|
|
|
### Static-First Philosophy
|
|
|
|
Classes are namespacing tools. Use static unless instances needed (models, resources). Avoid dependency injection.
|
|
|
|
### No Field Aliasing
|
|
|
|
**Field names must be identical across all layers.** Database → PHP → JSON → JavaScript: same names, always.
|
|
|
|
```php
|
|
// ❌ WRONG - renaming during serialization
|
|
return ['type_label' => $contact->type_id_label];
|
|
|
|
// ✅ CORRECT - names match source
|
|
return ['type_id_label' => $contact->type_id_label];
|
|
```
|
|
|
|
One string everywhere. Grep finds all usages. No mental mapping between layers.
|
|
|
|
### Git Workflow - Framework is READ-ONLY
|
|
|
|
**NEVER modify `/var/www/html/system/`** - It's like node_modules or the Linux kernel.
|
|
|
|
- **App repo**: `/var/www/html/.git` (you control)
|
|
- **Framework**: `/var/www/html/system/` (submodule, don't touch)
|
|
- **Your code**: `/var/www/html/rsx/` (all changes here)
|
|
|
|
**Commit discipline**: ONLY commit when explicitly asked. Commits are milestones, not individual changes.
|
|
|
|
### Class Overrides
|
|
|
|
To customize framework classes without modifying `/system/`, copy them to `rsx/` with the same class name. The manifest automatically uses your version and renames the framework file to `.upstream`.
|
|
|
|
**Common override targets** (copy from `system/app/RSpade/Core/Models/`):
|
|
- `User_Model` - Add custom fields, relationships, methods
|
|
- `User_Profile_Model` - Extend profile data
|
|
- `Site_Model` - Add site-specific settings
|
|
|
|
```bash
|
|
cp system/app/RSpade/Core/Models/User_Model.php rsx/models/user_model.php
|
|
# Edit namespace to Rsx\Models, customize as needed
|
|
```
|
|
|
|
Details: `php artisan rsx:man class_override`
|
|
|
|
### Trust Code Quality Rules
|
|
|
|
Each `rsx:check` rule has remediation text that tells AI assistants exactly what to do:
|
|
- Some rules say "fix immediately"
|
|
- Some rules say "present options and wait for decision"
|
|
|
|
AI should follow the rule's guidance precisely. Rules are deliberately written and well-reasoned.
|
|
|
|
---
|
|
|
|
## NAMING CONVENTIONS
|
|
|
|
**Enforced by `rsx:check`**:
|
|
|
|
| Context | Convention | Example |
|
|
|---------|------------|---------|
|
|
| PHP Methods/Variables | `underscore_case` | `user_name` |
|
|
| PHP Classes | `Like_This` | `User_Controller` |
|
|
| JavaScript Classes | `Like_This` | `User_Card` |
|
|
| Files | `lowercase_underscore` | `user_controller.php` |
|
|
| Database Tables | `lowercase_plural` | `users` |
|
|
| Constants | `UPPERCASE` | `MAX_SIZE` |
|
|
|
|
### File Prefix Grouping
|
|
|
|
Files sharing a common prefix are a related set. When renaming, maintain the grouping across ALL files with that prefix.
|
|
|
|
**Example** - `rsx/app/frontend/calendar/`:
|
|
```
|
|
frontend_calendar_event.scss
|
|
frontend_calendar_event_controller.php
|
|
frontend_calendar_event.jqhtml
|
|
frontend_calendar_event.js
|
|
```
|
|
|
|
**Critical**: Never create same-name different-case files (e.g., `user.php` and `User.php`).
|
|
|
|
### Component Naming Pattern
|
|
|
|
Input components follow: `{Supertype}_{Variant}_{Supertype}` → e.g., `Select_Country_Input`, `Select_State_Input`, `Select_Ajax_Input`
|
|
|
|
---
|
|
|
|
## DIRECTORY STRUCTURE
|
|
|
|
```
|
|
/var/www/html/
|
|
├── rsx/ # YOUR CODE
|
|
│ ├── app/ # Modules
|
|
│ ├── models/ # Database models
|
|
│ ├── services/ # Background tasks, external integrations
|
|
│ ├── public/ # Static files (web-accessible)
|
|
│ ├── resource/ # Framework-ignored
|
|
│ └── theme/ # Global assets
|
|
└── system/ # FRAMEWORK (read-only)
|
|
```
|
|
|
|
**Services**: Extend `Rsx_Service_Abstract` for non-HTTP functionality like scheduled tasks or external system integrations.
|
|
|
|
### Special Directories (Path-Agnostic)
|
|
|
|
**`resource/`** - ANY directory named this is framework-ignored. Store helpers, docs, third-party code. Exception: `/rsx/resource/config/` IS processed.
|
|
|
|
**`public/`** - ANY directory named this is web-accessible, framework-ignored. 5min cache, 30d with `?v=`.
|
|
|
|
### Path-Agnostic Loading
|
|
|
|
Classes found by name, not path. No imports needed.
|
|
|
|
```php
|
|
$user = User_Model::find(1); // Framework finds it
|
|
// NOT: use Rsx\Models\User_Model; // Auto-generated
|
|
```
|
|
|
|
---
|
|
|
|
## CONFIGURATION
|
|
|
|
**Two-tier system**:
|
|
- **Framework**: `/system/config/rsx.php` (never modify)
|
|
- **User**: `/rsx/resource/config/rsx.php` (your overrides)
|
|
|
|
Merged via `array_merge_deep()`. Common overrides: `development.auto_rename_files`, `bundle_aliases`, `console_debug`.
|
|
|
|
---
|
|
|
|
## ROUTING & CONTROLLERS
|
|
|
|
```php
|
|
class Frontend_Controller extends Rsx_Controller_Abstract
|
|
{
|
|
public static function pre_dispatch(Request $request, array $params = [])
|
|
{
|
|
if (!Session::is_logged_in()) return response_unauthorized();
|
|
return null;
|
|
}
|
|
|
|
#[Route('/', methods: ['GET'])]
|
|
public static function index(Request $request, array $params = [])
|
|
{
|
|
return rsx_view('Frontend_Index', [
|
|
'bundle' => Frontend_Bundle::render()
|
|
]);
|
|
}
|
|
}
|
|
```
|
|
|
|
**Rules**: Only GET/POST. Use `:param` syntax. Manual auth checks in pre_dispatch or method body.
|
|
|
|
### Authentication Pattern
|
|
|
|
```php
|
|
// Controller-wide auth (recommended)
|
|
public static function pre_dispatch(Request $request, array $params = []) {
|
|
if (!Session::is_logged_in()) return response_unauthorized();
|
|
return null;
|
|
}
|
|
|
|
```
|
|
|
|
### Type-Safe URLs
|
|
|
|
**MANDATORY**: All URLs must be generated using `Rsx::Route()` - hardcoded URLs are forbidden.
|
|
|
|
```php
|
|
// PHP - Controller (defaults to 'index' method)
|
|
Rsx::Route('User_Controller')
|
|
|
|
// PHP - Controller with explicit method. Passing an integer for param two implies the param two is 'id' (id=123)
|
|
Rsx::Route('User_Controller::show', 123);
|
|
|
|
// PHP - With query parameters. Extra params not defined in route itself become query string - automatically URL-encoded
|
|
Rsx::Route('Login_Controller::logout', ['redirect' => '/dashboard']);
|
|
// Generates: /logout?redirect=%2Fdashboard
|
|
|
|
// JavaScript (identical syntax)
|
|
Rsx.Route('User_Controller')
|
|
Rsx.Route('User_Controller::show', 123);
|
|
Rsx.Route('Login_Controller::logout', {redirect: '/dashboard'});
|
|
```
|
|
- **Unimplemented routes**: Prefix method with `#` → `Rsx::Route('Feature::#index')` generates `href="#"` and bypasses validation
|
|
|
|
**Enforcement**: `rsx:check` will flag hardcoded URLs like `/login` or `/logout?redirect=...` and require you to use `Rsx::Route()`. Do it right the first time to avoid rework.
|
|
|
|
---
|
|
|
|
## SPA (SINGLE PAGE APPLICATION) ROUTING
|
|
|
|
Client-side routing for authenticated application areas. One PHP bootstrap controller, multiple JavaScript actions that navigate without page reloads.
|
|
|
|
### SPA Components
|
|
|
|
**1. PHP Bootstrap Controller** - ONE per module with auth in pre_dispatch
|
|
```php
|
|
public static function pre_dispatch(Request $request, array $params = []) {
|
|
if (!Session::is_logged_in()) return response_unauthorized();
|
|
return null;
|
|
}
|
|
|
|
#[SPA]
|
|
public static function index(Request $request, array $params = []) {
|
|
return rsx_view(SPA);
|
|
}
|
|
```
|
|
One #[SPA] per module at `rsx/app/(module)/(module)_spa_controller::index`. Segregates code by permission level.
|
|
|
|
**2. JavaScript Actions (MANY)**
|
|
```javascript
|
|
@route('/contacts')
|
|
@layout('Frontend_Layout')
|
|
@spa('Frontend_Spa_Controller::index')
|
|
@title('Contacts') // Optional browser title
|
|
class Contacts_Index_Action extends Spa_Action {
|
|
async on_load() {
|
|
this.data.contacts = await Frontend_Contacts_Controller.datagrid_fetch();
|
|
}
|
|
}
|
|
```
|
|
|
|
**3. Layout**
|
|
```javascript
|
|
class Frontend_Layout extends Spa_Layout {
|
|
on_action(url, action_name, args) {
|
|
// Called after action created, before on_ready
|
|
// Access this.action immediately
|
|
this.update_navigation(url);
|
|
}
|
|
}
|
|
```
|
|
|
|
Layout template must have `$sid="content"` element where actions render.
|
|
|
|
### URL Generation & Navigation
|
|
|
|
```php
|
|
// PHP/JavaScript - same syntax
|
|
Rsx::Route('Contacts_Index_Action') // /contacts
|
|
Rsx::Route('Contacts_View_Action', 123) // /contacts/123
|
|
```
|
|
|
|
```javascript
|
|
Spa.dispatch('/contacts/123'); // Programmatic navigation
|
|
Spa.layout // Current layout instance
|
|
Spa.action // Current action instance
|
|
```
|
|
|
|
### URL Parameters
|
|
|
|
```javascript
|
|
// URL: /contacts/123?tab=history
|
|
@route('/contacts/:id')
|
|
class Contacts_View_Action extends Spa_Action {
|
|
on_create() {
|
|
console.log(this.args.id); // "123" (route param)
|
|
console.log(this.args.tab); // "history" (query param)
|
|
}
|
|
}
|
|
```
|
|
|
|
### File Organization
|
|
|
|
Pattern: `/rsx/app/(module)/(feature)/`
|
|
- **Module**: Major functionality (login, frontend, root)
|
|
- **Feature**: Screen within module (contacts, reports, invoices)
|
|
- **Submodule**: Feature grouping (settings), often with sublayouts
|
|
|
|
```
|
|
/rsx/app/frontend/ # Module
|
|
├── Frontend_Spa_Controller.php # Single SPA bootstrap
|
|
├── Frontend_Layout.js
|
|
├── Frontend_Layout.jqhtml
|
|
└── contacts/ # Feature
|
|
├── frontend_contacts_controller.php # Ajax endpoints only
|
|
├── Contacts_Index_Action.js # /contacts
|
|
├── Contacts_Index_Action.jqhtml
|
|
├── Contacts_View_Action.js # /contacts/:id
|
|
└── Contacts_View_Action.jqhtml
|
|
```
|
|
|
|
**Use SPA for:** Authenticated areas, dashboards, admin panels
|
|
**Avoid for:** Public pages (SEO needed), simple static pages
|
|
|
|
### Sublayouts
|
|
|
|
**Sublayouts** are `Spa_Layout` classes for nested persistent UI (e.g., settings sidebar). Use multiple `@layout` decorators - first is outermost: `@layout('Frontend_Spa_Layout')` then `@layout('Settings_Layout')`. Each must have `$sid="content"`. Layouts persist when unchanged; only differing parts recreated. All receive `on_action(url, action_name, args)` with final action info.
|
|
|
|
Details: `php artisan rsx:man spa`
|
|
|
|
### View Action Pattern
|
|
|
|
Three-state pattern for data-loading actions:
|
|
|
|
```javascript
|
|
on_create() {
|
|
this.data.record = { name: '' }; // Stub
|
|
this.data.error_data = null;
|
|
this.data.loading = true;
|
|
}
|
|
async on_load() {
|
|
try { this.data.record = await Controller.get({id: this.args.id}); }
|
|
catch (e) { this.data.error_data = e; }
|
|
this.data.loading = false;
|
|
}
|
|
```
|
|
|
|
Template: `<Loading_Spinner>` → `<Universal_Error_Page_Component>` → content. Details: `rsx:man view_action_patterns`
|
|
|
|
---
|
|
|
|
## CONVERTING BLADE PAGES TO SPA ACTIONS
|
|
|
|
For converting server-side Blade pages to client-side SPA actions, see `php artisan rsx:man blade_to_spa`.
|
|
The process involves creating Action classes with @route decorators and converting templates from Blade to jqhtml syntax.
|
|
|
|
---
|
|
|
|
## BLADE & VIEWS
|
|
|
|
**Note**: SPA pages are the preferred standard. Use Blade only for SEO-critical public pages or authentication flows.
|
|
|
|
```blade
|
|
@rsx_id('Frontend_Index') {{-- Every view starts with this --}}
|
|
<body class="{{ rsx_body_class() }}"> {{-- Adds view class --}}
|
|
```
|
|
|
|
**NO inline styles, scripts, or event handlers** - Use companion `.scss` and `.js` files.
|
|
**jqhtml components** work fully in Blade (no slots).
|
|
|
|
### SCSS Component-First Architecture
|
|
|
|
SCSS in `rsx/app/` and `rsx/theme/components/` must wrap in a single component class matching the jqhtml/blade file. Components auto-render with `class="Component_Name"` on root. `rsx/lib/` is non-visual. `rsx/theme/` (outside components/) holds primitives, variables, Bootstrap overrides.
|
|
|
|
**BEM**: Child classes use component's exact name as prefix. `.Component_Name { &__element }` → HTML: `<div class="Component_Name__element">` (no kebab-case).
|
|
|
|
**Variables**: `rsx/theme/variables.scss` - must be included before directory includes in bundles. Multiple SCSS files can target same component if primary file exists.
|
|
|
|
Details: `php artisan rsx:man scss`
|
|
|
|
### Responsive Breakpoints
|
|
|
|
RSX replaces Bootstrap breakpoints with semantic names. **Bootstrap defaults (col-md-6, d-lg-none) do NOT work.**
|
|
|
|
| Tier 1 | Range | Tier 2 | Range |
|
|
|--------|-------|--------|-------|
|
|
| `mobile` | 0-1023px | `phone` | 0-799px |
|
|
| `desktop` | 1024px+ | `tablet` | 800-1023px |
|
|
| | | `desktop-sm` | 1024-1199px |
|
|
| | | `desktop-md` | 1200-1639px |
|
|
| | | `desktop-lg` | 1640-2199px |
|
|
| | | `desktop-xl` | 2200px+ |
|
|
|
|
**SCSS**: `@include mobile { }`, `@include desktop { }`, `@include phone { }`, `@include desktop-xl { }`, etc.
|
|
**Classes**: `.col-mobile-6`, `.d-desktop-none`, `.mobile-only`, `.hide-tablet`
|
|
**JS**: `Responsive.is_mobile()`, `Responsive.is_phone()`, `Responsive.is_desktop_xl()`, etc.
|
|
|
|
Details: `php artisan rsx:man responsive`
|
|
|
|
### JavaScript for Blade Pages
|
|
|
|
Unlike SPA actions (which use component lifecycle), Blade pages use static `on_app_ready()` with a page guard:
|
|
|
|
```javascript
|
|
class My_Page { // Matches @rsx_id('My_Page')
|
|
static on_app_ready() {
|
|
if (!$('.My_Page').exists()) return; // Guard required - fires for ALL pages in bundle
|
|
// Page code here
|
|
}
|
|
}
|
|
```
|
|
|
|
### Passing Data to JavaScript
|
|
|
|
Use `@rsx_page_data` for page-specific data needed by JavaScript (IDs, config, etc.):
|
|
|
|
```blade
|
|
@rsx_page_data(['user_id' => $user->id, 'mode' => 'edit'])
|
|
|
|
@section('content')
|
|
<!-- Your HTML -->
|
|
@endsection
|
|
```
|
|
|
|
Access in JavaScript:
|
|
```javascript
|
|
const user_id = window.rsxapp.page_data.user_id;
|
|
```
|
|
|
|
Use when data doesn't belong in DOM attributes. Multiple calls merge together.
|
|
|
|
---
|
|
|
|
## BUNDLE SYSTEM
|
|
|
|
**One bundle per module (rsx/app/(module)).** Compiles JS/CSS automatically on request - no manual build steps.
|
|
|
|
```php
|
|
class Frontend_Bundle extends Rsx_Bundle_Abstract
|
|
{
|
|
public static function define(): array
|
|
{
|
|
return [
|
|
'include' => [
|
|
'jquery', // Required
|
|
'lodash', // Required
|
|
'rsx/theme/variables.scss', // Order matters
|
|
'rsx/theme', // Everything else from theme - but variables.scss will be first
|
|
'rsx/app/frontend', // Directory -
|
|
'rsx/models', // For JS stubs
|
|
],
|
|
];
|
|
}
|
|
}
|
|
```
|
|
|
|
```blade
|
|
<head>
|
|
{!! Frontend_Bundle::render() !!}
|
|
</head>
|
|
```
|
|
|
|
---
|
|
|
|
## JQHTML COMPONENTS
|
|
|
|
### Philosophy
|
|
|
|
For mechanical thinkers who see structure, not visuals. Write `<User_Card>` not `<div class="card">`. Name what things ARE.
|
|
|
|
### Template Syntax
|
|
|
|
**CRITICAL: `<Define>` IS the element, not a wrapper**
|
|
|
|
```jqhtml
|
|
<!-- ✅ CORRECT - Define becomes button -->
|
|
<Define:Save_Button tag="button" class="btn btn-primary">
|
|
Save
|
|
</Define:Save_Button>
|
|
|
|
<!-- Renders as: -->
|
|
<button class="Save_Button Component btn btn-primary">Save</button>
|
|
```
|
|
|
|
**Interpolation**: `<%= escaped %>` | `<%!= unescaped %>` | `<% javascript %>`
|
|
**Conditional Attributes** `<input <% if (this.args.required) { %>required="required"<% } %> />`
|
|
**Inline Logic**: `<% this.handler = () => action(); %>` then `@click=this.handler` - No JS file needed for simple components
|
|
**Event Handlers**: `@click=this.method` (unquoted) - Methods defined inline or in companion .js
|
|
**Validation**: `<% if (!this.args.required) throw new Error('Missing arg'); %>` - Fail loud in template
|
|
|
|
### Simple Components (No JS File)
|
|
|
|
```jqhtml
|
|
<Define:CSV_Renderer>
|
|
<%
|
|
if (!this.args.csv_data) throw new Error('csv_data required');
|
|
const rows = this.args.csv_data.split('\n').map(r => r.split(','));
|
|
this.toggle = () => { this.args.expanded = !this.args.expanded; this.render(); };
|
|
%>
|
|
<table>
|
|
<% for (let row of rows) { %>
|
|
<tr><% for (let cell of row) { %><td><%= cell %></td><% } %></tr>
|
|
<% } %>
|
|
</table>
|
|
<button @click=this.toggle>Toggle View</button>
|
|
</Define:CSV_Renderer>
|
|
```
|
|
|
|
Use inline JS for simple transformations/handlers. Create .js file when JS overwhelms template or needs external data.
|
|
|
|
### State Management Rules (ENFORCED)
|
|
|
|
**Quick Guide:**
|
|
- Loading from API? → Use `this.data` in `on_load()`
|
|
- Need reload with different params? → Modify `this.args`, call `reload()`
|
|
- UI state (toggles, selections)? → Use `this.state`
|
|
|
|
**this.args** - Component arguments (read-only in on_load(), modifiable elsewhere)
|
|
**this.data** - Ajax-loaded data (writable ONLY in on_create() and on_load())
|
|
**this.state** - Arbitrary component state (modifiable anytime)
|
|
|
|
```javascript
|
|
// WITH Ajax data
|
|
class Users_List extends Component {
|
|
on_create() {
|
|
this.data.users = []; // Defaults
|
|
}
|
|
async on_load() {
|
|
this.data.users = await User_Controller.fetch({filter: this.args.filter});
|
|
}
|
|
on_ready() {
|
|
// Change filter → reload
|
|
this.args.filter = 'new';
|
|
this.reload();
|
|
}
|
|
}
|
|
|
|
// WITHOUT Ajax data
|
|
class Toggle_Button extends Component {
|
|
on_create() {
|
|
this.state = {is_open: false};
|
|
}
|
|
on_ready() {
|
|
this.$.on('click', () => {
|
|
this.state.is_open = !this.state.is_open;
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
**on_load() restrictions** (enforced):
|
|
- ✅ Read `this.args`, write `this.data`
|
|
- ❌ NO DOM access, NO `this.state`, NO modifying `this.args`
|
|
|
|
### Lifecycle
|
|
|
|
1. **on_create()** → Setup defaults (sync) - `this.data.rows = []; this.data.loading = true;`
|
|
2. **render** → Template executes
|
|
3. **on_render()** → Hide uninitialized UI (sync)
|
|
4. **on_load()** → Fetch data into `this.data` (async)
|
|
5. **on_ready()** → DOM manipulation safe (async)
|
|
|
|
If `on_load()` modifies `this.data`, component renders twice (defaults → populated).
|
|
|
|
### Component API
|
|
|
|
**DOM Access:**
|
|
|
|
| Method | Returns | Purpose |
|
|
|--------|---------|---------|
|
|
| `this.$` | jQuery | Root element (NOT `this.$el`) |
|
|
| `this.$sid('name')` | jQuery | Child with `$sid="name"` |
|
|
| `this.sid('name')` | Component/null | Child component instance |
|
|
|
|
**reload() vs render():**
|
|
```
|
|
reload() = on_load() → render() → on_ready() ← ALWAYS USE THIS
|
|
render() = template only (no on_ready) ← NEVER USE
|
|
```
|
|
|
|
After mutations, call `this.reload()` - the server round-trip is intentional:
|
|
```javascript
|
|
async add_item() {
|
|
await Controller.add({name: 'Test'});
|
|
this.reload(); // Refreshes this.data via on_load(), reattaches handlers via on_ready()
|
|
}
|
|
```
|
|
|
|
**Event handlers** go in `on_ready()` - they auto-reattach after reload. **WRONG:** Event delegation like `this.$.on('click', '[data-sid="btn"]', handler)` to "survive" render calls - use `reload()` instead.
|
|
|
|
**this.data rules (enforced):** Writable only in `on_create()` (defaults) and `on_load()` (fetched data). Read-only elsewhere.
|
|
|
|
**on_render():** Ignore - use `on_ready()` for post-render work.
|
|
|
|
### Loading Pattern
|
|
|
|
```javascript
|
|
async on_load() {
|
|
const result = await Product_Controller.list({page: 1});
|
|
this.data.products = result.products;
|
|
this.data.loaded = true; // Simple flag at END
|
|
}
|
|
```
|
|
|
|
```jqhtml
|
|
<% if (!this.data.loaded) { %>
|
|
Loading...
|
|
<% } else { %>
|
|
<!-- Show data -->
|
|
<% } %>
|
|
```
|
|
|
|
**NEVER call `this.render()` in `on_load()` - automatic re-render happens.**
|
|
|
|
### Attributes
|
|
|
|
- **`$quoted="string"`** → String literal
|
|
- **`$unquoted=expression`** → JavaScript expression
|
|
- **`$sid="name"`** → Scoped element ID
|
|
- **`attr="<%= expr %>"`** → HTML attribute with interpolation
|
|
|
|
**Key restrictions:**
|
|
- **`<Define>` attributes are static** - No `<%= %>` on the `<Define>` tag. For dynamic attributes on the root element, use inline JS: `<% this.$.attr('data-id', this.args.id); %>`
|
|
- **`$prefix` = component args, NOT HTML attributes** - `<My_Component $data-id=123 />` creates `this.args['data-id']`, not a `data-id` DOM attribute
|
|
- **Conditional attributes use if-statements** - `<% if (cond) { %>checked<% } %>` not ternaries
|
|
|
|
### Component Access
|
|
|
|
**$sid** attribute = "scoped ID" - unique within component instance
|
|
|
|
From within component methods:
|
|
- **this.$** → jQuery selector for the component element itself
|
|
- **this.$sid(name)** → jQuery selector for child element with `$sid="name"`
|
|
- **this.sid(name)** → Component instance of child (or null if not a component)
|
|
- **$(selector).component()** → Get component instance from jQuery element
|
|
- **`await $(selector).component().ready()`** → Await component initialization. Rarely needed - `on_ready()` auto-waits for children created during render. Use for dynamically created components or Blade page JS interaction.
|
|
|
|
### Custom Component Events
|
|
|
|
Fire: `this.trigger('event_name', data)` | Listen: `this.sid('child').on('event_name', (component, data) => {})`
|
|
|
|
**Key difference from jQuery**: Events fired BEFORE handler registration still trigger the callback when registered. This solves component lifecycle timing issues where child events fire before parent registers handlers. Never use `this.$.trigger()` for custom events (enforced by JQHTML-EVENT-01).
|
|
|
|
### Dynamic Component Creation
|
|
|
|
To dynamically create/replace a component in JavaScript:
|
|
```javascript
|
|
// Destroys existing component (if any) and creates new one in its place
|
|
$(selector).component('Component_Name', { arg1: value1, arg2: value2 });
|
|
|
|
// Example: render a component into a container
|
|
this.$sid('result_container').component('My_Component', {
|
|
data: myData,
|
|
some_option: true
|
|
});
|
|
```
|
|
|
|
**Class preservation**: Only PascalCase component names (capital start, no `__`) are replaced. Utility classes (`text-muted`), BEM child classes (`Parent__child`), and all attributes are preserved.
|
|
|
|
### Incremental Scaffolding
|
|
|
|
**Undefined components work immediately** - they render as div with the component name as a class.
|
|
|
|
```blade
|
|
<Dashboard>
|
|
<Stats_Panel />
|
|
<Recent_Activity />
|
|
</Dashboard>
|
|
```
|
|
|
|
### Key Pitfalls
|
|
|
|
- `<Define>` IS the element - use `tag=""` attribute
|
|
- `this.data` starts `{}` - set defaults in `on_create()`
|
|
- `this.data` writable only in `on_create()` and `on_load()`
|
|
- `on_load()`: only `this.args` and `this.data` (no DOM, no `this.state`)
|
|
- `this.state` for UI state, `this.args` + `reload()` for refetch
|
|
- `Controller.method()` not `$.ajax()` - #[Ajax_Endpoint] auto-callable
|
|
- `on_create/render/stop` sync; `this.sid()` → component, `$(el).component()` → component
|
|
|
|
---
|
|
|
|
## FORM COMPONENTS
|
|
|
|
**Form fields** (`<Rsx_Form>` with `$data`, `$controller`, `$method`):
|
|
```blade
|
|
<Rsx_Form $data="{!! json_encode($form_data) !!}" $controller="Controller" $method="save">
|
|
<Form_Field $name="email" $label="Email" $required=true>
|
|
<Text_Input $type="email" />
|
|
</Form_Field>
|
|
|
|
<Form_Field_Hidden $name="id" />
|
|
</Rsx_Form>
|
|
```
|
|
|
|
- **Form_Field** - Standard formatted field with label, errors, help text
|
|
- **Form_Field_Hidden** - Single-tag hidden input (extends Form_Field_Abstract)
|
|
- **Form_Field_Abstract** - Base class for custom formatting (advanced)
|
|
|
|
**Disabled fields**: Use `$disabled=true` attribute on input components to disable fields. Unlike standard HTML, disabled fields still return values via `vals()` (useful for read-only data that should be submitted).
|
|
|
|
```blade
|
|
<Text_Input $type="email" $disabled=true />
|
|
<Select_Input $options="{!! json_encode($options) !!}" $disabled=true />
|
|
<Checkbox_Input $label="Subscribe" $disabled=true />
|
|
```
|
|
|
|
**Form component classes** use the **vals() dual-mode pattern**:
|
|
|
|
```javascript
|
|
class My_Form extends Component {
|
|
vals(values) {
|
|
if (values) {
|
|
// Setter - populate form
|
|
this.$sid('name').val(values.name || '');
|
|
return null;
|
|
} else {
|
|
// Getter - extract values
|
|
return {name: this.$sid('name').val()};
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Validation**: `Form_Utils.apply_form_errors(form.$, errors)` - Matches by `name` attribute.
|
|
|
|
### Form Conventions (Action/Controller Pattern)
|
|
|
|
Forms follow a load/save pattern mirroring traditional Laravel: Action loads data, Controller saves it.
|
|
|
|
```javascript
|
|
// Action: on_create() sets defaults, on_load() fetches for edit mode
|
|
on_create() {
|
|
this.data.form_data = { title: '', status_id: Model.STATUS_ACTIVE };
|
|
this.data.is_edit = !!this.args.id;
|
|
}
|
|
async on_load() {
|
|
if (!this.data.is_edit) return;
|
|
const record = await My_Model.fetch(this.args.id);
|
|
this.data.form_data = { id: record.id, title: record.title };
|
|
}
|
|
```
|
|
|
|
```php
|
|
// Controller: save() receives all form values, validates, persists
|
|
#[Ajax_Endpoint]
|
|
public static function save(Request $request, array $params = []) {
|
|
if (empty($params['title'])) return response_form_error('Validation failed', ['title' => 'Required']);
|
|
$record = $params['id'] ? My_Model::find($params['id']) : new My_Model();
|
|
$record->title = $params['title'];
|
|
$record->save();
|
|
return ['redirect' => Rsx::Route('View_Action', $record->id)];
|
|
}
|
|
```
|
|
|
|
**Key principles**: form_data must be serializable (plain objects, no models) | Keep load/save in same controller for field alignment | on_load() loads data, on_ready() is UI-only
|
|
|
|
Details: `php artisan rsx:man form_conventions`
|
|
|
|
### Polymorphic Form Fields
|
|
|
|
For fields that can reference multiple model types (e.g., an Activity linked to either a Contact or Project), use JSON-encoded polymorphic values.
|
|
|
|
```php
|
|
use App\RSpade\Core\Polymorphic_Field_Helper;
|
|
|
|
$eventable = Polymorphic_Field_Helper::parse($params['eventable'], [
|
|
Contact_Model::class,
|
|
Project_Model::class,
|
|
]);
|
|
|
|
if ($error = $eventable->validate('Please select an entity')) {
|
|
$errors['eventable'] = $error;
|
|
}
|
|
|
|
$model->eventable_type = $eventable->model;
|
|
$model->eventable_id = $eventable->id;
|
|
```
|
|
|
|
Client submits: `{"model":"Contact_Model","id":123}`. Always use `Model::class` for the whitelist.
|
|
|
|
Details: `php artisan rsx:man polymorphic`
|
|
|
|
---
|
|
|
|
## MODALS
|
|
|
|
### Built-in Dialog Types
|
|
|
|
| Method | Returns | Description |
|
|
|--------|---------|-------------|
|
|
| `Modal.alert(body)` | `void` | Simple notification |
|
|
| `Modal.alert(title, body, buttonLabel?)` | `void` | Alert with title |
|
|
| `Modal.confirm(body)` | `boolean` | Yes/no confirmation |
|
|
| `Modal.confirm(title, body, confirmLabel?, cancelLabel?)` | `boolean` | Confirmation with labels |
|
|
| `Modal.prompt(body)` | `string\|false` | Text input |
|
|
| `Modal.prompt(title, body, default?, multiline?)` | `string\|false` | Prompt with options |
|
|
| `Modal.select(body, options)` | `string\|false` | Dropdown selection |
|
|
| `Modal.select(title, body, options, default?, placeholder?)` | `string\|false` | Select with options |
|
|
| `Modal.error(error, title?)` | `void` | Error with red styling |
|
|
| `Modal.unclosable(title, body)` | `void` | Modal user cannot close |
|
|
|
|
```javascript
|
|
await Modal.alert("File saved");
|
|
if (await Modal.confirm("Delete?")) { /* confirmed */ }
|
|
const name = await Modal.prompt("Enter name:");
|
|
const choice = await Modal.select("Choose:", [{value: 'a', label: 'A'}, {value: 'b', label: 'B'}]);
|
|
await Modal.error("Something went wrong");
|
|
```
|
|
|
|
### Form Modals
|
|
|
|
```javascript
|
|
const result = await Modal.form({
|
|
title: "Edit User",
|
|
component: "User_Form",
|
|
component_args: {data: user},
|
|
on_submit: async (form) => {
|
|
const response = await User_Controller.save(form.vals());
|
|
if (response.errors) {
|
|
Form_Utils.apply_form_errors(form.$, response.errors);
|
|
return false; // Keep open
|
|
}
|
|
return response.data; // Close and return
|
|
}
|
|
});
|
|
```
|
|
|
|
Form component must implement `vals()` and include `<div $sid="error_container"></div>`.
|
|
|
|
### Modal Classes
|
|
|
|
For complex/reusable modals, create dedicated classes:
|
|
|
|
```javascript
|
|
class Add_User_Modal extends Modal_Abstract {
|
|
static async show() {
|
|
return await Modal.form({...}) || false;
|
|
}
|
|
}
|
|
|
|
// Usage
|
|
const user = await Add_User_Modal.show();
|
|
if (user) {
|
|
grid.reload();
|
|
await Next_Modal.show(user.id);
|
|
}
|
|
```
|
|
|
|
Pattern: Extend `Modal_Abstract`, implement static `show()`, return data or `false`.
|
|
|
|
Details: `php artisan rsx:man modals`
|
|
|
|
---
|
|
|
|
## JQUERY EXTENSIONS
|
|
|
|
| Method | Purpose |
|
|
|--------|---------|
|
|
| `.exists()` | Check element exists (instead of `.length > 0`) |
|
|
| `.shallowFind(selector)` | Find children without nested component interference |
|
|
| `.closest_sibling(selector)` | Search within ancestor hierarchy |
|
|
| `.checkValidity()` | Form validation helper |
|
|
| `.click()` | Auto-prevents default |
|
|
| `.click_allow_default()` | Native click behavior |
|
|
|
|
Details: `php artisan rsx:man jquery`
|
|
|
|
---
|
|
|
|
## MODELS & DATABASE
|
|
|
|
### No Mass Assignment
|
|
|
|
```php
|
|
// ✅ CORRECT
|
|
$user = new User_Model();
|
|
$user->email = $email;
|
|
$user->save();
|
|
|
|
// ❌ WRONG
|
|
User_Model::create(['email' => $email]);
|
|
```
|
|
|
|
### Enums
|
|
|
|
**CRITICAL: Read `php artisan rsx:man enum` for complete documentation before implementing.**
|
|
|
|
Integer-backed enums with model-level mapping to constants, labels, and custom properties. Uses BEM-style double underscore naming for magic properties.
|
|
|
|
```php
|
|
class Project_Model extends Rsx_Model_Abstract {
|
|
public static $enums = [
|
|
'status_id' => [
|
|
1 => ['constant' => 'STATUS_ACTIVE', 'label' => 'Active', 'badge' => 'bg-success', 'order' => 1],
|
|
2 => ['constant' => 'STATUS_ARCHIVED', 'label' => 'Archived', 'selectable' => false, 'order' => 99],
|
|
],
|
|
];
|
|
}
|
|
|
|
// Usage - BEM-style: field__property (double underscore)
|
|
$project->status_id = Project_Model::STATUS_ACTIVE;
|
|
echo $project->status_id__label; // "Active"
|
|
echo $project->status_id__badge; // "bg-success" (custom property)
|
|
```
|
|
|
|
**Special properties**:
|
|
- `order` - Sort position in dropdowns (default: 0, lower first)
|
|
- `selectable` - Include in dropdown options (default: true). Non-selectable items excluded from `field__enum_select()` but still shown if current value.
|
|
|
|
**JavaScript static methods** (BEM-style double underscore):
|
|
```js
|
|
// Get all enum data
|
|
Project_Model.status_id__enum()
|
|
|
|
// Get specific enum's metadata by ID
|
|
Project_Model.status_id__enum(Project_Model.STATUS_ACTIVE).badge // "bg-success"
|
|
Project_Model.status_id__enum(2).selectable // false
|
|
|
|
// Other methods
|
|
Project_Model.status_id__enum_select() // For dropdowns
|
|
Project_Model.status_id__enum_labels() // id => label map
|
|
Project_Model.status_id__enum_ids() // Array of valid IDs
|
|
```
|
|
|
|
**Migration:** Use BIGINT for enum columns, TINYINT(1) for booleans. Run `rsx:migrate:document_models` after adding enums.
|
|
|
|
### Model Fetch
|
|
|
|
```php
|
|
#[Ajax_Endpoint_Model_Fetch]
|
|
public static function fetch($id)
|
|
{
|
|
if (!Session::is_logged_in()) return false;
|
|
return static::find($id);
|
|
}
|
|
```
|
|
|
|
```javascript
|
|
const project = await Project_Model.fetch(1); // Throws if not found
|
|
const maybe = await Project_Model.fetch_or_null(999); // Returns null if not found
|
|
console.log(project.status_id__label); // Enum properties (BEM-style)
|
|
console.log(Project_Model.STATUS_ACTIVE); // Static enum constants
|
|
|
|
// Lazy relationships (requires #[Ajax_Endpoint_Model_Fetch] on relationship method)
|
|
const client = await project.client(); // belongsTo → Model or null
|
|
const tasks = await project.tasks(); // hasMany → Model[]
|
|
```
|
|
|
|
**Security**: Both `fetch()` and relationships require `#[Ajax_Endpoint_Model_Fetch]` attribute. Related models must also implement `fetch()` with this attribute.
|
|
|
|
**fetch() is for SECURITY, not aliasing**: The `fetch()` method exists to remove private data users shouldn't see. NEVER alias enum properties (e.g., `type_label` instead of `type_id__label`) or format dates server-side. Use the full BEM-style names and format dates on client with `Rsx_Date`/`Rsx_Time`.
|
|
|
|
Details: `php artisan rsx:man model_fetch`
|
|
|
|
### Migrations
|
|
|
|
**Forward-only, no rollbacks. Deterministic transformations against known state.**
|
|
|
|
```bash
|
|
php artisan make:migration:safe create_users_table
|
|
php artisan migrate:begin
|
|
php artisan migrate
|
|
php artisan migrate:commit
|
|
```
|
|
|
|
**NO defensive coding in migrations:**
|
|
```php
|
|
// ❌ WRONG - conditional logic
|
|
$fk_exists = DB::select("SELECT ... FROM information_schema...");
|
|
if (!empty($fk_exists)) { DB::statement("ALTER TABLE foo DROP FOREIGN KEY bar"); }
|
|
|
|
// ✅ CORRECT - direct statements
|
|
DB::statement("ALTER TABLE foo DROP FOREIGN KEY bar");
|
|
DB::statement("ALTER TABLE foo DROP COLUMN baz");
|
|
```
|
|
|
|
No `IF EXISTS`, no `information_schema` queries, no fallbacks. Know current state, write exact transformation. Failures fail loud - snapshot rollback exists for recovery.
|
|
|
|
---
|
|
|
|
## FILE ATTACHMENTS
|
|
|
|
Files upload UNATTACHED → validate → assign via API. Session-based validation prevents cross-user file assignment.
|
|
|
|
```php
|
|
// Controller: Assign uploaded file
|
|
$attachment = File_Attachment_Model::find_by_key($params['photo_key']);
|
|
if ($attachment && $attachment->can_user_assign_this_file()) {
|
|
$attachment->attach_to($user, 'profile_photo'); // Single (replaces)
|
|
$attachment->add_to($project, 'documents'); // Multiple (adds)
|
|
}
|
|
|
|
// Model: Retrieve attachments
|
|
$photo = $user->get_attachment('profile_photo');
|
|
$documents = $project->get_attachments('documents');
|
|
|
|
// Display
|
|
$photo->get_thumbnail_url('cover', 128, 128);
|
|
$photo->get_url();
|
|
$photo->get_download_url();
|
|
```
|
|
|
|
**Endpoints:** `POST /_upload`, `GET /_download/:key`, `GET /_thumbnail/:key/:type/:width/:height`
|
|
|
|
Details: `php artisan rsx:man file_upload`
|
|
|
|
---
|
|
|
|
## POLYMORPHIC TYPE REFERENCES
|
|
|
|
Polymorphic `*_type` columns (fileable_type, taskable_type, etc.) store BIGINT integers in the database for efficiency. The framework maps between integer IDs and class names transparently.
|
|
|
|
```php
|
|
// Model: Declare type ref columns
|
|
protected static $type_ref_columns = ['fileable_type'];
|
|
|
|
// Usage: Code works with class name strings - conversion is automatic
|
|
$attachment->fileable_type = 'Contact_Model'; // Stored as integer in DB
|
|
echo $attachment->fileable_type; // Reads as 'Contact_Model'
|
|
```
|
|
|
|
**Simple Names Only**: Always use `class_basename($model)`, never `get_class($model)` (FQCNs)
|
|
|
|
Details: `php artisan rsx:man polymorphic`
|
|
|
|
---
|
|
|
|
## AJAX ENDPOINTS
|
|
|
|
```php
|
|
#[Ajax_Endpoint]
|
|
public static function method(Request $request, array $params = []) {
|
|
return $data; // Success - framework wraps as {_success: true, _ajax_return_value: ...}
|
|
}
|
|
```
|
|
|
|
**PHP→JS Auto-mapping:**
|
|
```php
|
|
// PHP: My_Controller class
|
|
#[Ajax_Endpoint]
|
|
public static function save(Request $request, array $params = []) {
|
|
return ['id' => 123];
|
|
}
|
|
|
|
// JS: Automatically callable
|
|
const result = await My_Controller.save({name: 'Test'});
|
|
console.log(result.id); // 123
|
|
```
|
|
|
|
### Error Responses
|
|
|
|
Use `response_error(Ajax::ERROR_CODE, $metadata)`:
|
|
|
|
```php
|
|
// Not found
|
|
return response_error(Ajax::ERROR_NOT_FOUND, 'Project not found');
|
|
|
|
// Validation
|
|
return response_error(Ajax::ERROR_VALIDATION, [
|
|
'email' => 'Invalid',
|
|
'name' => 'Required'
|
|
]);
|
|
|
|
// Auto-message
|
|
return response_error(Ajax::ERROR_UNAUTHORIZED);
|
|
```
|
|
|
|
**Codes:** `ERROR_VALIDATION`, `ERROR_NOT_FOUND`, `ERROR_UNAUTHORIZED`, `ERROR_AUTH_REQUIRED`, `ERROR_FATAL`, `ERROR_GENERIC`
|
|
|
|
**Client:**
|
|
```javascript
|
|
try {
|
|
const data = await Controller.get(id);
|
|
} catch (e) {
|
|
if (e.code === Ajax.ERROR_NOT_FOUND) {
|
|
// Handle
|
|
} else {
|
|
alert(e.message); // Generic
|
|
}
|
|
}
|
|
```
|
|
|
|
Unhandled errors auto-show flash alert.
|
|
|
|
---
|
|
|
|
## DATA FETCHING (CRITICAL)
|
|
|
|
**DEFAULT**: Use `Model.fetch(id)` for all single-record retrieval from JavaScript.
|
|
|
|
```javascript
|
|
const user = await User_Model.fetch(1); // Throws if not found
|
|
const user = await User_Model.fetch_or_null(1); // Returns null if not found
|
|
```
|
|
|
|
Requires `#[Ajax_Endpoint_Model_Fetch]` on the model's `fetch()` method.
|
|
|
|
Auto-populates enum properties and enables lazy relationship loading.
|
|
|
|
**If model not available in JS bundle**: STOP and ask the developer. Bundles should include all models they need (`rsx/models` in include paths). Do not create workaround endpoints without approval.
|
|
|
|
**Custom Ajax endpoints require developer approval** and are only for:
|
|
- Aggregations, batch operations, or complex result sets
|
|
- System/root-only models intentionally excluded from bundle
|
|
- Queries beyond simple ID lookup
|
|
|
|
Details: `php artisan rsx:man model_fetch`
|
|
|
|
---
|
|
|
|
## AUTHENTICATION
|
|
|
|
**Always use Session** - Static methods only. Never Laravel Auth or $_SESSION.
|
|
|
|
```php
|
|
Session::is_logged_in(); // Returns true if user logged in
|
|
Session::get_user(); // Returns user model or null
|
|
Session::get_user_id(); // Returns user ID or null
|
|
Session::get_site(); // Returns site model
|
|
Session::get_site_id(); // Returns current site ID
|
|
Session::get_session_id(); // Returns session ID
|
|
```
|
|
|
|
Sessions persist 365 days. Never implement "Remember Me".
|
|
|
|
---
|
|
|
|
## DATE & TIME HANDLING
|
|
|
|
**Two Classes - Strict Separation**: `Rsx_Time` (datetimes with timezone) | `Rsx_Date` (calendar dates, no timezone)
|
|
|
|
**String-Based Philosophy**: RSpade uses ISO strings, not Carbon objects. Dates are `"2025-12-24"`, datetimes are `"2025-12-24T15:30:00-06:00"`. Same format in PHP, JavaScript, JSON, database queries. No object serialization issues.
|
|
|
|
**Model Casts**: `Rsx_Model_Abstract` auto-applies `Rsx_Date_Cast` (DATE columns) and `Rsx_DateTime_Cast` (DATETIME columns). Never define `$casts` with `'date'`, `'datetime'`, or `'timestamp'` - these use Carbon and are blocked by `rsx:check`.
|
|
|
|
### Rsx_Time - Moments in Time
|
|
```php
|
|
use App\RSpade\Core\Time\Rsx_Time;
|
|
|
|
Rsx_Time::now(); // Current time in user's timezone
|
|
Rsx_Time::now_iso(); // ISO 8601 format: 2025-12-24T15:30:00-06:00
|
|
Rsx_Time::format($datetime); // "Dec 24, 2025 3:30 PM"
|
|
Rsx_Time::format_short($datetime); // "Dec 24, 3:30 PM"
|
|
Rsx_Time::to_database($datetime); // UTC for storage
|
|
|
|
Rsx_Time::get_user_timezone(); // User's timezone or default
|
|
```
|
|
|
|
```javascript
|
|
Rsx_Time.now(); // Current moment (timezone-aware)
|
|
Rsx_Time.format(datetime); // Formatted for display
|
|
Rsx_Time.relative(datetime); // "2 hours ago", "in 3 days"
|
|
```
|
|
|
|
### Rsx_Date - Calendar Dates
|
|
```php
|
|
use App\RSpade\Core\Time\Rsx_Date;
|
|
|
|
Rsx_Date::today(); // "2025-12-24" (user's timezone)
|
|
Rsx_Date::format($date); // "Dec 24, 2025"
|
|
Rsx_Date::is_today($date); // Boolean
|
|
Rsx_Date::is_past($date); // Boolean
|
|
```
|
|
|
|
**Key Principle**: Functions throw if wrong type passed (datetime to date function or vice versa).
|
|
|
|
### Server Time Sync
|
|
Client time syncs automatically via rsxapp data on page load and AJAX responses. No manual sync required.
|
|
|
|
### User Timezone
|
|
Stored in `login_users.timezone` (IANA format). Falls back to `config('rsx.datetime.default_timezone')`.
|
|
|
|
Details: `php artisan rsx:man time`
|
|
|
|
---
|
|
|
|
## JAVASCRIPT DECORATORS
|
|
|
|
```javascript
|
|
/** @decorator */
|
|
function logCalls(target, key, descriptor) { /* ... */ }
|
|
|
|
class Service {
|
|
@logCalls
|
|
@mutex
|
|
async save() { /* ... */ }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## COMMANDS
|
|
|
|
### Module Creation
|
|
|
|
```bash
|
|
rsx:app:module:create <name> # /name
|
|
rsx:app:module:feature:create <m> <f> # /m/f
|
|
rsx:app:component:create --name=x # Component
|
|
```
|
|
|
|
### Development
|
|
|
|
```bash
|
|
rsx:check # Code quality
|
|
rsx:debug /page # Test routes (see below)
|
|
rsx:man <topic> # Documentation
|
|
db:query "SQL" --json
|
|
```
|
|
|
|
### Testing Routes
|
|
|
|
**`rsx:debug /path`** - Uses Playwright to render pages with full JS execution.
|
|
|
|
```bash
|
|
rsx:debug /dashboard --user=1 # Authenticated user
|
|
rsx:debug /page --screenshot-path=/tmp/page.png # Capture screenshot
|
|
rsx:debug /contacts --eval="$('.btn').click(); await sleep(1000)" # Simulate interaction
|
|
rsx:debug / --eval="return Rsx_Time.now_iso()" # Get eval result (use return)
|
|
rsx:debug / --console --eval="console.log(Rsx_Date.today())" # Or console.log with --console
|
|
```
|
|
|
|
Options: `--user=ID`, `--console`, `--screenshot-path`, `--screenshot-width=mobile|tablet|desktop-*`, `--dump-dimensions=".selector"`, `--eval="js"`, `--help`
|
|
|
|
**SPA routes ARE server routes.** If you get 404, the route doesn't exist - check route definitions. Never dismiss as "SPA can't be tested server-side".
|
|
|
|
**rsx:debug captures the fully-rendered final DOM state** after all async operations, component lifecycles, and data loading complete. If the DOM doesn't match expectations, it's not a timing issue - what you see is what the user sees. Investigate the actual code, not the capture timing.
|
|
|
|
### Debugging
|
|
|
|
- **rsx_dump_die()** - Debug output
|
|
- **console_debug("CHANNEL", ...)** - Channel logging
|
|
- **CONSOLE_DEBUG_FILTER=CHANNEL** - Filter output
|
|
|
|
---
|
|
|
|
## ERROR HANDLING
|
|
|
|
```php
|
|
if (!$expected) {
|
|
shouldnt_happen("Class {$expected} missing");
|
|
}
|
|
```
|
|
|
|
Use for "impossible" conditions that indicate broken assumptions.
|
|
|
|
---
|
|
|
|
## CODE QUALITY
|
|
|
|
**Professional UI**: Hover effects ONLY on buttons, links, form fields. Static elements remain static.
|
|
|
|
**z-index**: Bootstrap defaults + 1100 (modal children), 1200 (flash alerts), 9000+ (system). Details: `rsx:man zindex`
|
|
|
|
Run `rsx:check` before commits. Enforces naming, prohibits animations on non-actionable elements.
|
|
|
|
---
|
|
|
|
## KEY REMINDERS
|
|
|
|
1. **Fail loud** - No silent failures
|
|
2. **Static by default** - Unless instances needed
|
|
3. **Path-agnostic** - Reference by name
|
|
4. **Bundles required** - For JavaScript
|
|
5. **Use Session** - Never Laravel Auth
|
|
6. **No mass assignment** - Explicit only
|
|
7. **Forward migrations** - No rollbacks
|
|
8. **Don't run rsx:clean** - Cache auto-invalidates
|
|
9. **All routes need auth checks** - In pre_dispatch() or method body (@auth-exempt for public)
|
|
|
|
---
|
|
|
|
## GETTING HELP
|
|
|
|
```bash
|
|
php artisan rsx:man <topic> # Framework documentation
|
|
php artisan list rsx # All commands
|
|
```
|
|
|
|
**Topics**: bundle_api, jqhtml, routing, migrations, console_debug, model_fetch, vs_code_extension, deployment, framework_divergences
|
|
|
|
---
|
|
|
|
## PROJECT DOCUMENTATION
|
|
|
|
Project-specific man pages in `/rsx/resource/man/*.txt`. Create when features have non-obvious details or component interactions. See `/rsx/resource/man/CLAUDE.md` for format.
|