Modal Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require corepine/modal
   php artisan vendor:publish --tag=corepine-modal-config
   

   Add Tailwind CSS import to your main file:

   @import "../../vendor/corepine/modal/resources/css/app.css";
   

2. Livewire Stack Mode Setup: Include the modal host in your layout (e.g., app.blade.php):

   <x-corepine.modal.assets />
   

3. First Modal: Create a Livewire modal class:

   php artisan make:livewire MyModal
   

   Extend Corepine\Modal\Modal:

   use Corepine\Modal\Modal;
   
   class MyModal extends Modal
   {
       public $name = 'John Doe';
   }
   

   Trigger it from a button:

   <x-corepine.modal.trigger wire:click="$openModal('MyModal')" />
   

4. Standalone Alpine Mode: Use the component directly in Blade:

   <x-corepine.modal
       wire:ignore
       x-data="{ open: false }"
       @open.window="open = true"
       @close.window="open = false"
   >
       <div x-show="open">
           <!-- Modal content -->
       </div>
   </x-corepine.modal>
   

Implementation Patterns

Core Workflows

1. Livewire Stack-Based Modals

• Modal Hierarchy: Child modals automatically stack on top of parent modals. Use $openModal() to trigger nested modals.

  // Parent modal
  public function openChildModal()
  {
      $this->openModal('ChildModal', ['param' => 'value']);
  }
  

• Shell Actions: Define actions in your modal class to handle form submissions or dismissals:

  public function save()
  {
      // Logic
      $this->close();
  }
  

2. Standalone Alpine + Blade Modals

• Event-Driven: Use Alpine’s x-data and @open.window/@close.window for browser-triggered modals.

  <x-corepine.modal
      x-data="{ open: false }"
      @open.window="open = true"
  >
      <div x-show="open" x-transition>
          <!-- Content -->
      </div>
  </x-corepine.modal>
  

• No Livewire: Ideal for simple modals (e.g., tooltips, alerts) where Livewire overhead isn’t needed.

3. Modal Types

• Dialog (modal): Default centered modal.
• Drawer (drawer): Left/right panel (use direction="left|right").
• Sheet (sheet): Bottom-up modal (use type="sheet").

  <x-corepine.modal type="sheet" direction="left">
      <!-- Content -->
  </x-corepine.modal>
  

Integration Tips

• Package-Safe Events: Use Corepine\Modal\Events to dispatch/modal-specific events (e.g., ModalOpened).
• Configuration: Customize default behavior via config/corepine-modal.php (e.g., backdrop opacity, animations).
• Livewire + Alpine Sync: For hybrid setups, use wire:model to sync Livewire properties with Alpine state:

  <input wire:model="name" x-model="localName" @change="name = localName">
  

Gotchas and Tips

Pitfalls

1. Livewire Host Missing:

   • Error: Modals fail to render or stack incorrectly.
   • Fix: Ensure <x-corepine.modal.assets /> is included in your layout once.

2. Modal Stack Leaks:

   • Issue: Child modals remain open after parent closes due to improper $close() calls.
   • Fix: Always call $this->close() in shell actions or use $this->closeModal() to target specific modals.

3. Tailwind Conflicts:

   • Problem: Custom styles override package CSS.
   • Solution: Scope your Tailwind classes (e.g., .my-modal .bg-blue-500) or use !important sparingly.

4. Alpine + Livewire State Clashes:

   • Symptom: Alpine state resets when Livewire updates.
   • Workaround: Use wire:ignore on Alpine-managed elements or sync state explicitly.

Debugging

• Check Stack Order: Use browser dev tools to inspect z-index layers. Corepine modals use a base z-50 with increments for stacking.
• Event Listeners: Verify custom events are dispatched via Tinker:

  php artisan tinker
  >>> event(new \Corepine\Modal\Events\ModalOpened('MyModal'));
  

• Livewire Logs: Enable Livewire debugging in .env:

  LIVEWIRE_LOG_LEVEL=debug
  

Extension Points

1. Custom Modal Classes:

   • Override Corepine\Modal\Modal to add shared logic (e.g., auth checks):

     class AuthModal extends Modal
     {
         public function mount()
         {
             if (!auth()->check()) {
                 $this->close();
             }
         }
     }
     

2. Dynamic Content:

   • Use Blade slots or Livewire properties to inject dynamic content:

     <x-corepine.modal>
         <x-slot name="title">
             {{ $this->title ?? 'Default Title' }}
         </x-slot>
     </x-corepine.modal>
     

3. Animation Overrides:

   • Extend the package’s Tailwind classes in your CSS:

     @layer components.modal {
         .corepine-modal-enter-active {
             @apply transition-all duration-300;
         }
     }
     

4. Package-Safe Event Names:

   • Prefix custom events to avoid collisions:

     $this->dispatch('my-package::modal-opened', modal: $this);
     

   • Listen in config:

     'events' => [
         'opened' => 'my-package::modal-opened',
     ],