Wire Modals Laravel Package

Getting Started

1. Install the package with Composer and publish any config/assets it ships (php artisan vendor:publish). Confirm the service provider is auto-discovered.
2. Read the package README for the minimal modal registration, then read docs/sylloo-migration-prompt.md if you are replacing an existing modal/component loader. That guide is the fastest path if you already have a hand-rolled dynamic loader.
3. Wire one modal into an existing Livewire component. The first practical use case is replacing a manually managed modal — e.g. a Bootstrap modal toggled with Alpine or jQuery — with a wire-modal component triggered from a Livewire action.
4. Decide up front whether you are adopting the package in legacy mode (compatibility with your existing loader) or directly in the modern API. For most existing apps, start in legacy mode and migrate after the first working modal.

Implementation Patterns

• Declarative modal composition. Define modals as Blade/Livewire components and mount them from a parent view. Keep modal content in its own component rather than embedding large forms in the parent.
• Action-driven opening. Trigger modals from Livewire methods rather than DOM click handlers where possible. This keeps server-side authorization, validation, and data loading in one place.
• Legacy-first migration. Use the new migration guide's sequence for apps with a custom dynamic loader: keep the existing loader API surface, route it through wire-modals in legacy mode, verify behavior, then replace the loader with native modal components.
• Parameter passing. Pass identifiers or DTOs to modal components via public properties or mount parameters, and re-fetch authoritative data inside the modal component rather than trusting parent state.
• Nested/stacked modals. For confirmation dialogs inside edit modals, rely on the package's stack behavior rather than hand-managing z-index or visibility flags.
• Event integration. Use Livewire events (dispatch/listen) for cross-component communication — e.g. a table row dispatches an "open modal" event handled by a modal host component. Keep event payloads small and serializable.
• Progressive modernisation. Once legacy mode is stable, migrate one modal at a time to the modern API; avoid a big-bang rewrite.

Gotchas and Tips

• Don’t mix legacy and modern modes in the same flow. The migration guide explicitly recommends legacy mode first, then modernisation for a reason: mode boundaries are where state and event-handling bugs appear.
• The migration prompt is a guide, not an automated codemod. Treat docs/sylloo-migration-prompt.md as a checklist. Verify each step against your loader's actual behavior, especially how it resolved component names dynamically.
• Modal state on re-render. Livewire re-renders can reset local Alpine state or lose focus. Keep form state in Livewire public properties and use stable wire:key values for list items inside modals.
• Event name collisions. If your existing loader already dispatches generic events like open-modal, namespace new events or remove the old listeners before enabling the package to avoid double-opening.
• Config quirks. Check published config for view namespace, component path, and legacy-mode flags. Cached config (config:cache) can mask changes during migration.
• Debugging. Use Livewire's browser event inspection and Livewire::test(...)->assertDispatched(...) in tests to confirm modal events fire. If a modal doesn't open, verify both the dispatch and that a modal host is mounted on the page.
• Extension points. Prefer custom modal components and config overrides over patching vendor views. If you need bespoke behavior, wrap the package's modal component rather than forking it, so future releases remain upgradeable.
• Upgrade note for 1.0.1. This release only adds documentation; no runtime changes. Existing installs do not need code changes, but teams planning a migration should adopt the new guide as their standard sequence.