Livewire Slide Overs Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require laravelcm/livewire-slide-overs

Publish the config (if needed) with:

php artisan vendor:publish --provider="Laravelcm\LivewireSlideOvers\SlideOverServiceProvider"

2. Basic Usage: Add the root component to your layout:

   @livewire('slide-over-panel')
   

   Trigger a slide-over instantly with:

   <!-- Instant open (no animation) -->
   <button wire:click="$emit('slideOverOpenInstant', 'unique-id')">Open Instantly</button>
   
   <!-- Standard open (with animation) -->
   <button wire:click="$emit('slideOverOpen', 'unique-id')">Open with Animation</button>
   

3. First Slide-Over: Define a slide-over in your Blade template with optional dynamic resize:

   <livewire:slide-over-panel.child
       id="unique-id"
       title="My Slide Over"
       :open="false"
       :resizable="true"  <!-- New: Enable dynamic resizing -->
       :native-dialog="true"  <!-- New: Native browser dialog mode -->
   >
       <!-- Slide-over content -->
       <p>This is my slide-over content.</p>
   </livewire:slide-over-panel.child>
   

Implementation Patterns

Core Workflow

1. Component Hierarchy:

   • Root: @livewire('slide-over-panel') (manages state, animations, and new features like native-dialog).
   • Children: <livewire:slide-over-panel.child> (individual slide-overs with optional resizable and native-dialog props).
   • Triggers:
     • $emit('slideOverOpen', 'id') → Standard animated open.
     • $emit('slideOverOpenInstant', 'id') → New: Instant open (no animation).
     • $emit('slideOverClose', 'id') → Close slide-over.

2. Dynamic Slide-Overs with New Features: Dynamically register slide-overs with enhanced options:

   public $slideOvers = [
       'id-1' => [
           'title' => 'Dynamic Title',
           'content' => '<p>Dynamic content</p>',
           'resizable' => true,       // New: Enable resizing
           'native_dialog' => false,  // New: Use native dialog mode
       ],
       'id-2' => [
           'title' => 'Native Dialog',
           'content' => '<p>Uses browser dialog</p>',
           'native_dialog' => true,   // New: Native dialog mode
       ],
   ];
   

   Render them in Blade:

   @foreach($slideOvers as $id => $slideOver)
       <livewire:slide-over-panel.child
           id="{{ $id }}"
           title="{{ $slideOver['title'] }}"
           :open="false"
           :resizable="{{ $slideOver['resizable'] ?? false }}"
           :native-dialog="{{ $slideOver['native_dialog'] ?? false }}"
       >
           {!! $slideOver['content'] !!}
       </livewire:slide-over-panel.child>
   @endforeach
   

3. State Management:

   • Use wire:model to bind slide-over state to Livewire properties:

     <livewire:slide-over-panel.child
         id="my-id"
         wire:model="isOpen"
         :native-dialog="true"
     >
     

   • Access the root component’s state via $this->slideOverStates in your Livewire class.
   • New: Check for native_dialog mode in your logic:

     if ($this->slideOverStates['my-id']['native_dialog']) {
         // Handle native dialog behavior
     }
     

4. Native Dialog Mode:

   • Use Case: For slide-overs that need browser-native dialog behavior (e.g., modals with role="dialog").
   • Implementation:

     <livewire:slide-over-panel.child
         id="confirmation-dialog"
         title="Confirm Action"
         :native-dialog="true"
     >
         <p>Are you sure you want to proceed?</p>
     </livewire:slide-over-panel.child>
     

   • Note: Native dialog mode may override some animations and styling. Test responsiveness.

5. Dynamic Resizing:

   • Use Case: Slide-overs that need adjustable height (e.g., forms, tables).
   • Implementation:

     <livewire:slide-over-panel.child
         id="resizable-panel"
         :resizable="true"
     >
         <div class="h-[300px] overflow-auto"> <!-- Content with scrollable area -->
             <!-- Resize handle (auto-injected by package) -->
         </div>
     </livewire:slide-over-panel.child>
     

   • Customization: Override the resize handle in your child component’s template.

6. Custom Animations for New Modes: Extend the child component to customize animations for native-dialog or resizable slide-overs:

   class CustomNativeDialog extends SlideOverPanelChild
   {
       public function slideOverAnimation()
       {
           return 'transition ease-out duration-200';
       }
   
       public function slideOverClass()
       {
           return parent::slideOverClass() . ' backdrop-blur-sm';
       }
   }
   

Gotchas and Tips

Pitfalls

1. ID Collisions:

   • Slide-over IDs must be unique across the entire app. Reusing IDs will cause state conflicts.
   • Fix: Use UUIDs or namespaced IDs (e.g., user-profile-settings, cart-sidebar).

2. Native Dialog Quirks:

   • Browser Behavior: Native dialog mode (native-dialog="true") may behave differently across browsers (e.g., focus trapping, scroll locking).
   • Fix: Test in target browsers. Override default styles if needed:

     .slide-over-panel.native-dialog {
         backdrop-filter: blur(5px);
     }
     

   • Accessibility: Native dialogs require proper ARIA attributes. The package auto-applies these, but verify with tools like axe.

3. Resizable Slide-Overs:

   • Performance: Dynamic resizing adds a resize handle and event listeners, which may impact performance with many slide-overs.
   • Fix: Disable resizing for non-interactive slide-overs:

     <livewire:slide-over-panel.child id="static-panel" :resizable="false" />
     

   • Styling Conflicts: Ensure the resize handle doesn’t conflict with your layout:

     .slide-over-panel.resizable .resize-handle {
         right: 2px;
         top: 0;
         width: 5px;
         background: #333;
     }
     

4. Instant Open vs. Standard Open:

   • Instant Open: Skips animations entirely. Use for performance-critical paths (e.g., error messages).
   • Standard Open: Preserves animations and transitions. Use for UX-sensitive slide-overs.
   • Fix: Avoid mixing both modes for the same slide-over ID to prevent state inconsistencies.

5. Livewire 3 vs. 4:

   • The package supports both Livewire 3.4+ and 4.x, but some syntax differs (e.g., $emit vs. $dispatch).
   • Fix: Check the changelog for version-specific notes.
   • New: Instant open events use $emit('slideOverOpenInstant'). Ensure your listeners are updated:

     protected $listeners = [
         'slideOverOpenInstant.*' => 'handleInstantOpen',
     ];
     

6. Z-Index Conflicts:

   • Slide-overs use a default z-index stack. Native dialogs may require higher z-index values.
   • Fix: Adjust the root component’s z-index in the published config or override it in your CSS:

     .slide-over-panel.native-dialog {
         z-index: 6000 !important;
     }
     

Debugging Tips

1. Inspect State: Add this to your root component to debug slide-over states (including new props):

   public function render()
   {
       dd($this->slideOverStates); // Check for 'resizable' and 'native_dialog' keys
       return view('livewire.slide-over-panel');
   }
   

2. Check for JavaScript Errors:

   • Native Dialogs: Ensure the browser supports dialog elements (modern browsers only). Fallback gracefully:

     @if (config('slide-over.native_dialog_fallback', false))
         <div class="fallback-dialog">...</div>
     @endif
     

   • Resizable Slide-Overs: Verify the resize handle is rendered and functional. Check for:
     • Missing Alpine.js (window.Alpine undefined).
     • Conflicting event listeners (