rspade_system/docs/BREAKING_CHANGES.md

RSpade Framework - Breaking Changes

This document tracks breaking changes in the RSpade framework that require developers to update their application code.

Format

Each breaking change entry includes:

• Date: When the change was introduced
• Component: Affected system/component
• Change: Description of what changed
• Migration: How to update existing code
• Impact: Severity (Critical/High/Medium/Low)

---

2025-11-03: Rsx_Form Automatic Submit Button Wiring

Component: Rsx_Form component Impact: Medium - Requires manual code updates to existing forms

Change

Rsx_Form now automatically wires all submit buttons (button[type="submit"]) to call the form's submit() method. Manual button wiring is no longer needed and should be removed.

Previous Pattern

class Frontend_Clients_Edit {
    static init() {
        // Wire save button to Rsx_Form component
        $('#save-btn').on('click', function() {
            const $form = $('.Rsx_Form').first();
            const form_component = $form.component();
            if (form_component) {
                form_component.submit();
            }
        });
    }
}

<button type="button" class="btn btn-primary" id="save-btn">
    Save Changes
</button>

New Pattern

class Frontend_Clients_Edit {
    static init() {
        // No initialization needed - submit button automatically wired by Rsx_Form
    }
}

<button type="submit" class="btn btn-primary">
    Save Changes
</button>

Migration Steps

1. Update button markup:

   • Change type="button" to type="submit"
   • Remove id attribute if only used for wiring

2. Remove manual wiring code:

   • Delete the $('#save-btn').on('click', ...) handler
   • If your init() function is now empty, you can leave it (it may be needed in the future) or add a comment explaining it's for future use

3. Test form submission:

   • Verify the form still submits correctly
   • Check validation error handling still works

Benefits

• Less boilerplate code
• More semantic HTML (type="submit")
• Consistent pattern across all forms
• Automatic event prevention (no need for e.preventDefault())

Notes

• This change only affects forms using the Rsx_Form component
• Custom submit logic (pre-submission validation, etc.) should now be handled differently - contact framework maintainer for patterns
• Forms with multiple submit buttons (e.g., "Save" vs "Save and Continue") will have all buttons wired - differentiate using button values or data attributes

---

2025-11-20: Unified Ajax Error Response System

Component: Ajax error handling Impact: Medium - Existing error handling code continues to work, but new pattern recommended

Change

Replaced fragmented error response helpers (response_form_error(), response_auth_required(), etc.) with unified response_error() function using constants for error codes. Same constant names on server and client for zero mental translation.

Previous Pattern

// Server - different functions for each error type
return response_form_error('Validation failed', ['email' => 'Invalid']);
return response_not_found('Project not found');
return response_unauthorized('Permission denied');

// Client - string matching with different names
if (error.type === 'form_error') { ... }
if (error.type === 'not_found') { ... }

New Pattern

// Server - single function with constants
return response_error(Ajax::ERROR_VALIDATION, ['email' => 'Invalid']);
return response_error(Ajax::ERROR_NOT_FOUND, 'Project not found');
return response_error(Ajax::ERROR_UNAUTHORIZED);  // Auto-message

// Client - same constant names
if (e.code === Ajax.ERROR_VALIDATION) { ... }
if (e.code === Ajax.ERROR_NOT_FOUND) { ... }

Migration Steps

1. Update server-side error responses to use response_error() with constants
2. Update client-side error checks to use e.code === Ajax.ERROR_* instead of e.type === 'string'
3. Read updated documentation: php artisan rsx:man ajax_error_handling

Old helpers still work but are deprecated. Framework code being updated to new pattern.

Benefits

• Same constant names server and client (Ajax::ERROR_NOT_FOUND = Ajax.ERROR_NOT_FOUND)
• IDE autocomplete for error codes
• Refactor-safe (rename constant updates both sides)
• Auto-generated messages for common errors
• Simpler API (one function instead of many)

---

Template for Future Entries

## YYYY-MM-DD: Brief Description

**Component**: Affected component/system
**Impact**: Critical/High/Medium/Low

### Change
Description of what changed and why.

### Previous Pattern
[Code example showing old way]

### New Pattern
[Code example showing new way]

### Migration Steps
1. Step one
2. Step two
3. Step three

### Benefits
- Benefit one
- Benefit two

### Notes
Additional context or edge cases.