Pounce Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awcodes/pounce
   

2. Theme Integration (required for Filament Panels): Update tailwind.config.js to include Pounce's views:

   content: [
       './vendor/awcodes/pounce/resources/**/*.blade.php',
       // ... other paths
   ]
   

   Run npm run dev or npm run build.

3. Register Plugin (for Filament Panels):

   public function panel(Panel $panel): Panel {
       return $panel->plugins([
           \Awcodes\Pounce\PouncePlugin::make(),
       ]);
   }
   

4. First Modal Usage:

   use Awcodes\Pounce\Facades\Pounce;
   
   // Trigger modal
   Pounce::modal('Confirm Action')
       ->content('Are you sure you want to proceed?')
       ->acceptButton('Delete')
       ->cancelButton('Cancel')
       ->accept(function () {
           // Handle acceptance
       })
       ->cancel(function () {
           // Handle cancellation
       })
       ->mount();
   

Implementation Patterns

Common Workflows

1. Dynamic Modal Content: Use Blade views or dynamic strings for content:

   Pounce::modal('Dynamic Content')
       ->content(view('modals.custom-modal', ['data' => $data]))
       ->mount();
   

2. Form Integration: Combine with Filament Forms for rich interactions:

   Pounce::modal('Edit Record')
       ->content(
           Form::make()
               ->schema([
                   TextInput::make('name')->required(),
               ])
               ->getWidget()
       )
       ->accept(function (array $data) {
           // Save logic
       })
       ->mount();
   

3. Reusable Modal Components: Create a service class for consistent modal patterns:

   class ModalService {
       public function confirm(string $title, string $message, callable $onAccept) {
           Pounce::modal($title)
               ->content($message)
               ->accept($onAccept)
               ->cancel(function () {})
               ->mount();
       }
   }
   

4. Panel-Specific Modals: Scope modals to specific panels by registering the plugin per-panel.

5. Livewire Integration: Mount modals from Livewire components:

   public function mount() {
       Pounce::modal('Livewire Modal')
           ->content('Content from Livewire')
           ->mount();
   }
   

Integration Tips

• Styling: Customize via Tailwind classes in the content() method:

  ->content('<div class="p-6 bg-gray-100">...</div>')
  

• Size Control: Use built-in size modifiers (small, large):

  ->size('large')
  

• Focus Management: Ensure focusable elements (e.g., inputs) are accessible post-mount.
• A11y: Add aria-label or aria-describedby for screen readers:

  ->content('<div id="modal-content" aria-describedby="modal-desc">...</div>')
  

Gotchas and Tips

Pitfalls

1. Theme Dependency:

   • Issue: Modals may not render without a custom theme (Filament Panels).
   • Fix: Follow Filament’s theme setup guide strictly.

2. Livewire Conflicts:

   • Issue: Nested Livewire components may cause modal content to re-render unexpectedly.
   • Fix: Use wire:ignore on modal content or lazy-load components.

3. Event Handling:

   • Issue: Closures in accept()/cancel() may not persist across requests.
   • Fix: Use wire:model.live or store logic in a service class.

4. Styling Overrides:

   • Issue: Tailwind classes may be purged if not referenced in tailwind.config.js.
   • Fix: Ensure all dynamic classes are included in content().

5. Z-Index Conflicts:

   • Issue: Modals may appear behind other elements (e.g., dropdowns).
   • Fix: Explicitly set z-index in your theme’s CSS:

     .pounce-modal { z-index: 50; }
     

Debugging

• Modal Not Showing?:

  • Check browser console for Tailwind/JS errors.
  • Verify the plugin is registered in the panel.
  • Ensure npm run dev was executed post-theme update.

• Closures Not Triggering:

  • Confirm the modal is mounted before the event (e.g., button click).
  • Use dd() in closures to debug execution flow.

Extension Points

1. Custom Animations: Extend the modal’s Alpine.js logic in resources/js/pounce.js:

   document.addEventListener('alpine:init', () => {
       Alpine.data('pounce', () => ({
           // Override transition logic
       }));
   });
   

2. Global Modal State: Use Alpine’s reactivity to manage state across modals:

   ->content('<div x-data="...">...</div>')
   

3. Server-Side Logic: Offload heavy processing to Livewire or controllers to avoid blocking the UI.

4. Testing: Use Filament’s testing helpers to assert modal interactions:

   $this->assertModalOpened('Confirm Action');
   $this->assertModalClosed();
   

Pro Tips

• Modal Stacking: Chain modals for nested workflows (e.g., confirm before delete).
• Localization: Pass translated strings to content() for i18n support.
• Performance: Lazy-load modal content for large forms/views.
• Dark Mode: Ensure Tailwind’s dark variants are configured in your theme.