Getting Started

Minimal Steps

Installation:
```
composer require nawasara/modal
```
The package is auto-discovered, so no additional configuration is required.

First Use Case - Blade Modal:

Add a modal to your Blade view:

<x-nawasara-modal::modal id="quick-example" title="Hello World">
    This is a simple modal.
</x-nawasara-modal::modal>

Trigger the modal with a button:

<button @click="openModal('quick-example')">Open Modal</button>

Include Alpine.js (if not already present) in your layout:
```
<script src="//unpkg.com/alpinejs" defer></script>
```

First Use Case - Livewire Modal:
- Add the universal Livewire modal component to your layout (e.g., resources/views/layouts/app.blade.php):
```
<livewire:nawasara-modal.livewire-modal />
```
- Open a Livewire component inside the modal from JavaScript:
```
openModal({
    id: 'livewire-modal',
    title: 'Livewire Example',
    component: 'your.livewire.component',
    params: { key: 'value' }
});
```
Verify Setup:
- Ensure the modal appears when triggered.
- For Livewire modals, confirm the component renders correctly inside the modal.

Implementation Patterns

Blade Modal Workflow

Component Placement:
- Place <x-nawasara-modal::modal> in your Blade view where the modal should appear (typically near the end of the <body> for proper stacking).
- Use unique id attributes for each modal to avoid conflicts.

Content Structure:

Use slots for modular content:

<x-nawasara-modal::modal id="form-modal" title="Create User">
    <x-slot:default>
        <form>
            <!-- Form fields -->
        </form>
    </x-slot:default>
    <x-slot:footer>
        <button type="submit">Save</button>
        <button @click="open = false">Cancel</button>
    </x-slot:footer>
</x-nawasara-modal::modal>

Triggering Modals:

Use Alpine.js to toggle visibility:

<button @click="openModal('form-modal')">Create User</button>

For dynamic triggers, pass data via Alpine:

<button @click="openModal('form-modal', { userId: 123 })">Edit User</button>

Styling and Theming:
- Override default styles by publishing the views:
```
php artisan vendor:publish --provider="Nawasara\Modal\ModalServiceProvider" --tag="modal-views"
```
- Customize the published Blade files in resources/views/vendor/nawasara-modal/.

Livewire Modal Workflow

Universal Component:
- Include <livewire:nawasara-modal.livewire-modal /> once in your layout (e.g., app.blade.php).
- This component manages all Livewire modals dynamically.
Opening Modals:
- Use the openModal JavaScript function to open any Livewire component:
```
openModal({
    id: 'user-modal',
    title: 'User Profile',
    component: 'user-profile-modal',
    params: { userId: 1 }
});
```
- The component value should match a registered Livewire component (e.g., UserProfileModal).

Livewire Component Setup:

Create a Livewire component for modal content (e.g., UserProfileModal):

namespace App\Livewire;

use Livewire\Component;

class UserProfileModal extends Component
{
    public $userId;

    public function mount($userId)
    {
        $this->userId = $userId;
    }

    public function render()
    {
        return view('livewire.user-profile-modal');
    }
}

Ensure the component accepts the params passed from openModal.

Handling Modal Data:

Access modal data in your Livewire component:

public function mount($userId)
{
    $this->userId = $userId;
    // Fetch data based on $userId
}

Close the modal programmatically:

// Inside your Livewire component's JS
window.closeModal('user-modal');

Dynamic Content:

Use Livewire’s reactivity to update modal content without page reloads:

public function updateProfile()
{
    // Update logic
    $this->emit('modalClosed', 'user-modal');
}

Integration Tips

Alpine.js Integration:
- Ensure Alpine.js is loaded before using modal triggers. Add this to your layout:
```
<script src="//unpkg.com/alpinejs" defer></script>
```
- For Laravel Mix/Vite, install Alpine.js as a dependency:
```
npm install alpinejs
```
  Then import it in your JavaScript entry file.
Livewire and Blade Hybrid:
- Use Blade modals for static content (e.g., alerts, simple forms).
- Use Livewire modals for dynamic content (e.g., forms with validation, real-time updates).

Modal Stacking:

To support nested modals, modify the openModal function to track the modal stack:

let modalStack = [];

function openModal(config) {
    modalStack.push(config.id);
    // Existing openModal logic
}

function closeModal(id) {
    modalStack = modalStack.filter(stackId => stackId !== id);
    // Existing closeModal logic
}

Form Handling:

For forms inside modals, use Livewire to handle submissions:

<x-nawasara-modal::modal id="form-modal" title="Submit Feedback">
    <livewire:feedback-form />
</x-nawasara-modal::modal>

Ensure the Livewire component emits events to close the modal on success:

public function submit()
{
    // Save logic
    $this->emit('closeModal', 'form-modal');
}

Accessibility:

Add ARIA attributes to improve accessibility:

<x-nawasara-modal::modal
    id="accessible-modal"
    title="Accessible Modal"
    aria-label="Important notification"
    aria-describedby="modal-description"
>
    <div id="modal-description">Modal content here.</div>
</x-nawasara-modal::modal>

Ensure modal triggers are keyboard-navigable (e.g., Tab and Enter support).

Gotchas and Tips

Pitfalls

Livewire Component Registration:
- Pitfall: Forgetting to register Livewire components in app/Providers/AppServiceProvider.php:
```
public function boot()
{
    $this->app->make(\Livewire\LivewireServiceProvider::class)->boot();
}
```
- Fix: Ensure Livewire is properly bootstrapped in your Laravel app.
Modal ID Conflicts:
- Pitfall: Using duplicate id attributes for modals causes the second modal to overwrite the first.
- Fix: Always use unique id values for each modal.

Alpine.js Scope Issues:

Pitfall: Modal triggers may not work if Alpine.js scope is not properly configured.

Fix: Use x-data to ensure Alpine reactivity:

<div x-data="{ open: false }">
    <button @click="open = true">Open</button>
    <x-nawasara-modal::modal id="dynamic-modal" x-show="open" x-transition>
        <!-- Modal content -->
    </x-nawasara-modal::modal>
</div>

Livewire Modal Performance:
- Pitfall: Heavy Livewire components inside modals can cause lag or timeouts.
- Fix:
  - Use wire:ignore for static content.
  - Lazy-load data in the mount method.
  - Example:
```
public function mount($userId)
{
    $this->user = User::find($userId); // Load data on mount
}
```
CSS Conflicts:
- Pitfall: Default modal styles may conflict with your app’s CSS framework (e.g., Tailwind, Bootstrap).
- Fix: Publish and override the views:
```
php artisan vendor:publish --provider="Nawasara\Modal\ModalServiceProvider" --tag="modal-views"
```
  Then customize the published Blade files.

Debugging Tips

Modal Not Opening:
- Check: Ensure Alpine.js is loaded and the openModal function is defined.
- Debug: Add a console log to verify the function

Modal Laravel Package