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: Documentation clarification - unified pattern is the only implemented pattern

Change

Adopted unified response_error() function with error code constants. Same constant names on server and client for zero mental translation.

Note: The fragmented helper functions (response_form_error(), response_auth_required(), etc.) shown in earlier documentation were a planned design that was superseded before implementation. Only response_error() exists.

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) { ... }

Documentation

See php artisan rsx:man ajax_error_handling for complete usage.

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.