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

```javascript
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();
            }
        });
    }
}
```

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

### New Pattern

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

```blade
<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

```php
// 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');
```

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

### New Pattern

```php
// 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
```

```javascript
// 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.
```