Filament Draggable Modal Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require sanzgrapher/filament-draggable-modal
   

   Ensure your project uses Filament v5 (compatibility is explicitly stated).

2. Registration: Add the plugin to your Panel in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(DraggableModalPlugin::make());
   }
   

3. First Use Case: Open any modal in your Filament admin panel (e.g., create/edit forms, confirmation dialogs). The modal header should now be draggable by default—no additional code required.

Implementation Patterns

Core Workflow

• Zero-Configuration Activation: The plugin auto-detects and enhances all modals in Filament v5. No need to manually mark specific modals for draggability.

• Integration with Custom Modals: If using custom modal components (e.g., via Modal facade or Modal::make()), ensure they extend Filament’s base modal structure. The plugin targets standard Filament modal classes by default.

• Conditional Activation: Disable draggability for specific modals by adding a data-draggable="false" attribute to the modal’s root element:

  <x-modal data-draggable="false">
      <!-- Modal content -->
  </x-modal>
  

Advanced Patterns

• Dynamic Handle Customization: Override the draggable handle (e.g., make the entire header draggable or add a custom grip):

  // In a custom JS file (e.g., via Filament's asset pipeline)
  document.addEventListener('DOMContentLoaded', () => {
      const modal = document.querySelector('[data-modal]');
      if (modal) {
          modal.setAttribute('data-draggable-handle', '.custom-handle-class');
      }
  });
  

• Responsive Behavior: Disable dragging on mobile devices by checking window.innerWidth in a custom script:

  if (window.innerWidth <= 768) {
      document.querySelectorAll('[data-modal]').forEach(modal => {
          modal.setAttribute('data-draggable', 'false');
      });
  }
  

• Event Listeners: Listen for drag events to trigger custom logic (e.g., save modal position in localStorage):

  document.addEventListener('draggableModalDragged', (e) => {
      const { modalId, position } = e.detail;
      localStorage.setItem(`modal-${modalId}-position`, JSON.stringify(position));
  });
  

  Note: Requires extending the plugin’s JS (see Extension Points).

Gotchas and Tips

Pitfalls

1. Filament Version Mismatch:

   • Issue: The plugin is Filament v5-only. Using it with v4 or v3 will break modal rendering.
   • Fix: Verify your filament/filament package version in composer.json (≥5.0.0).

2. CSS Conflicts:

   • Issue: Overly restrictive position: fixed or overflow: hidden on parent containers may prevent dragging.
   • Fix: Inspect the modal’s parent elements in DevTools. Add pointer-events: none to conflicting parents or adjust z-index.

3. Nested Modals:

   • Issue: Dragging a nested modal (e.g., a modal inside another modal) may cause unexpected behavior.
   • Fix: Disable draggability for nested modals via data-draggable="false".

4. Performance with Many Modals:

   • Issue: Heavy pages with 10+ modals may experience lag during drag operations.
   • Fix: Debounce drag events or lazy-load modals.

Debugging Tips

• Check Plugin Registration: Ensure DraggableModalPlugin::make() is called after ->id() and before ->discoverResources()/->discoverPages() in your panel() method.

• Console Errors: Open DevTools (F12) and check for errors like:

  • Uncaught TypeError: modal.addEventListener is not a function → Likely a Filament modal not being properly initialized. Update Filament or the plugin.
  • Cannot read property 'setAttribute' of null → The modal DOM isn’t ready. Wrap your custom JS in DOMContentLoaded.

• Visual Glitches:

  • Flickering: Increase the z-index of the modal or its handle.
  • Handle Not Clickable: Ensure the handle isn’t overlapping with interactive elements (e.g., buttons). Adjust padding/margins.

Extension Points

1. Custom Drag Logic: Extend the plugin’s JavaScript by publishing its assets:

   php artisan vendor:publish --tag=filament-draggable-modal-assets
   

   Then override resources/js/filament-draggable-modal.js and add your logic.

2. Server-Side Position Storage: Save modal positions to the database by hooking into Filament’s Saving event:

   use Filament\Notifications\Actions\Action;
   use Filament\Notifications\Notification;
   
   public function register(): void
   {
       Notification::macro('saveModalPosition', function ($modalId, $position) {
           // Save to DB or cache
       });
   }
   

3. Accessibility: Add ARIA attributes for screen readers:

   // In your custom JS
   modal.setAttribute('aria-grabbed', 'false');
   handle.addEventListener('mousedown', () => {
       modal.setAttribute('aria-grabbed', 'true');
   });
   

Pro Tips

• Default Position Reset: Reset all modal positions to default on login/logout:

  use Illuminate\Support\Facades\Event;
  
  Event::listen('filament.auth.login', function () {
      session()->forget('modal_positions');
  });
  

• Dark Mode Compatibility: Ensure the drag handle’s color contrasts in dark mode by adding:

  [data-draggable-handle] {
      background-color: rgba(var(--gray-800), 0.5);
  }
  

• Performance Optimization: Use passive event listeners for drag events:

  modal.addEventListener('mousemove', handler, { passive: true });