Rad Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   Add the bundle via Composer (updated for 4.0.3 compatibility):
   ```bash
   composer require becklyn/rad-bundle:^4.0

Register the bundle in config/bundles.php (unchanged):

return [
    // ...
    Becklyn\RadBundle\BecklynRadBundle::class => ['all' => true],
];

2. First Use Case: AJAX Response Inject AjaxResponseBuilder into a controller (updated for 4.0.3):

   use Becklyn\RadBundle\AjaxResponseBuilder;
   
   class MyController extends AbstractController
   {
       public function ajaxAction(AjaxResponseBuilder $builder): Response
       {
           return $builder
               ->ok()
               ->data(['key' => 'value'])
               ->build(); // 4.0.3 enforces stricter response validation
       }
   }
   

   Use the mojave client (ensure version ^3.2+ for compatibility):

   const response = await fetch('/ajax-endpoint');
   const result = await mojave.ajaxResponse(response);
   if (!result.ok) {
       console.error(`Status: ${result.status || 'unknown'}`);
   }
   

3. Form Extensions Extend a form type with RadFormExtension (4.0.3 adds lazyValidation option):

   use Becklyn\RadBundle\Form\Extension\RadFormExtension;
   
   class MyFormType extends AbstractType
   {
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder->addExtension(new RadFormExtension([
               'lazyValidation' => true, // NEW: Validate on blur by default
           ]));
       }
   }
   

Implementation Patterns

AJAX Workflows

1. Consistent Response Handling Use AjaxResponseBuilder with 4.0.3's stricter validation:

   return $builder
       ->ok()
       ->status('custom-status') // Must be non-empty string
       ->data(['items' => $items]) // Must be JSON-serializable
       ->message(['text' => 'Success!', 'impact' => 'positive']) // NEW: 'impact' is required
       ->build();
   

2. Frontend Integration Pair with mojave@^3.2 for TypeScript (4.0.3 adds result.meta support):

   if (result.meta?.redirect) {
       window.location.href = result.meta.redirect;
   }
   if (result.message?.impact) {
       mojave.toast(result.message.text, result.message.impact);
   }
   

3. Error Handling Return non-ok responses with descriptive status (4.0.3 reserves these):

   return $builder
       ->fail()
       ->status('invalid-data') // Must be one of: ['invalid-data', 'validation-error', 'auth-failed', 'server-error']
       ->data(['errors' => $errors])
       ->build();
   

Form Patterns

1. Dynamic Field Validation Use RadFormExtension with 4.0.3's lazyValidation:

   $builder->add('email', EmailType::class, [
       'constraints' => [new NotBlank(), new Email()],
       'attr' => ['data-rad-lazy' => true], // NEW: Opt-in per-field lazy validation
   ]);
   

2. Custom JavaScript Events Attach events via RadFormExtension (4.0.3 adds debounce option):

   $builder->addExtension(new RadFormExtension([
       'events' => [
           'submit' => [
               'handler' => 'myCustomSubmitHandler',
               'debounce' => 300, // NEW: Debounce in ms
           ],
       ],
   ]));
   

3. Nested Form Support Extend nested forms with 4.0.3's partialUpdate:

   $builder->add('address', AddressType::class, [
       'entry_options' => [
           'rad' => [
               'ajax' => true,
               'partialUpdate' => true, // NEW: Only update changed fields
           ],
       ],
   ]);
   

Integration Tips

1. Symfony UX Turbo/Stimulus Combine with Symfony UX (4.0.3 adds turbo:replace support):

   // Controller
   return $builder
       ->ok()
       ->data(['html' => $this->renderView('partial.html.twig')])
       ->meta(['turboAction' => 'replace']) // NEW: Turbo-specific meta
       ->build();
   

   // Stimulus controller
   connect() {
       this.fetch('/ajax-endpoint').then(response => {
           if (response.meta?.turboAction === 'replace') {
               this.element.replaceWith(response.data.html);
           }
       });
   }
   

2. API Platform Override serializeContext with 4.0.3's ajax_groups:

   public function serializeContext(Operation $operation, array $uriVariables = [], array $context = []): array
   {
       $context['groups'] = ['ajax', 'default'];
       $context['ajax_groups'] = ['items']; // NEW: Separate AJAX serialization groups
       return parent::serializeContext($operation, $uriVariables, $context);
   }
   

3. Custom Twig Functions Extend Twig with 4.0.3's ajax_include:

   {{ ajax_include('partial.html.twig', {
       'data': {'key': 'value'},
       'meta': {'turboAction': 'replace'}
   }) }}
   

Gotchas and Tips

Pitfalls

1. Deprecation Warning

   • The bundle is still deprecated in favor of becklyn/rad v8+.
   • 4.0.3 introduces breaking changes for custom response builders. Update to:

     class CustomResponseBuilder extends AjaxResponseBuilder
     {
         public function __construct()
         {
             parent::__construct(); // Must call parent constructor
         }
     }
     

2. TypeScript Mismatch

   • 4.0.3 enforces stricter response validation. Ensure mojave@^3.2+:

     // Handle unknown statuses
     if (!['ok', 'invalid-data', 'validation-error', 'auth-failed', 'server-error'].includes(result.status)) {
         throw new Error(`Unknown status: ${result.status}`);
     }
     

3. Form Extension Conflicts

   • 4.0.3 changes default behavior: lazyValidation is now true by default.
   • Disable globally in config/packages/rad_form.yaml:

     rad_form:
         default_lazy_validation: false
     

4. AJAX Redirects

   • 4.0.3 moves redirects to meta.redirect (deprecated redirect field):

     if (result.meta?.redirect) {
         window.location.href = result.meta.redirect;
     }
     

Debugging

1. Response Validation Use var_dump($builder->getResponse()) (4.0.3 adds validate() method):

   $response = $builder->build();
   $builder->validate($response); // Throws \InvalidArgumentException on errors
   

2. Frontend Errors Check for these 4.0.3-specific issues:

   • result.ok must be a boolean.
   • result.status must be a reserved string (see above).
   • result.data must be a plain object/array (no resources).
   • result.meta must be a plain object.

3. Form Events Debug with 4.0.3's rad:debug event:

   document.addEventListener('rad:debug', (e) => {
       console.log('Rad event:', e.detail);
   });
   

Configuration Quirks

1. Default AJAX Protocol

   • 4.0.3 changes default status code: Now returns 200 for all responses, but:
     • ok: false responses trigger rad:error event in frontend.
     • Configure error tracking to ignore ok: false with 200 status.

2. Twig Autoescape Disable autoescaping for AJAX HTML (4.0.3 adds ajax_safe filter):

   {{ render(controller('AppController::ajaxPartial'))|ajax_safe }}
   

3. CSRF Protection

   • 4.0.3 adds SameSite cookie support. Update mojave:

     mojave.fetch('/submit', {
         credentials: 'include', // NEW: Required for SameSite cookies
         headers: {
             'X-Requested-With':