Modal Laravel Package

Getting Started

1. composer require noerd-dev/modal and run the package's install/publish step from its README (config and front-end assets are typically published here — check for a vendor:publish tag before assuming defaults).
2. Read the config file first: it holds the knobs for stacked-depth behavior and fullscreen handling, which is where most day-to-day surprises live.
3. Skim the panel/component API next — you need to know how a "panel" is defined (class vs. Blade component vs. config array) before writing your first modal, since the package is panel-oriented rather than a single global modal.
4. First use case: a simple confirm dialog triggered from a Blade button. Once that works, immediately try a stacked flow (list → detail → edit) so you see the depth-scaling behavior early — it is the package's distinguishing feature and the thing that shapes your UI decisions.

Implementation Patterns

• Panel-per-purpose. Define discrete panels (confirm, create/edit form, detail preview) rather than one generic modal, and reuse them across controllers/views. This keeps depth-scaling predictable, since each stack level is a known panel.
• Stacked navigation flows. Open a second modal from inside the first for drill-down flows. Rely on the built-in depth scaling to visually communicate hierarchy instead of hand-rolling z-index and transform CSS.
• Opt out of scaling for heavy panels. Use forceModalFullscreen for wizards, long forms, or anything where a shrinking modal would clip content or make inputs unusable. As of v0.3.31 these panels hold full size at every depth, so this is now a safe, supported choice rather than a visual compromise.
• Livewire integration. Open a panel from a Livewire action, keep form state in the parent component, and close on successful save. Treat the modal as presentation, not as the owner of state.
• Progressive enhancement checks. Trigger the same panel both declaratively (Blade attribute/directive) and programmatically (from JS or a Livewire action) so you know both paths work before building on top of them.
• Testing. Assert modal visibility through whatever the package exposes (rendered markup or a Livewire assertion helper) rather than snapshotting HTML; the depth-scaling wrapper markup is an implementation detail likely to change.

Gotchas and Tips

• v0.3.31 behavior change: fullscreen panels no longer participate in stacked-depth scaling. If you built a nested flow and expected a fullscreen panel to shrink at depth ≥ 2, it now stays full size. This is almost certainly the desired behavior, but verify any screenshots/visual tests that encoded the old shrinking look.
• Scroll locking with nested modals. With two or more open panels, confirm body scroll lock releases correctly when closing the inner modal and not only the outer one; this is the most common source of "page won't scroll after closing" bugs.
• Dismissal semantics per panel. Backdrop-click and Escape should usually be disabled for destructive confirm panels but left on for informational ones. Set this per panel rather than globally.
• Z-index / stacking context. If a panel is opened from inside a container with its own transform or overflow: hidden (common in sidebars or sticky headers), the modal can render clipped or behind other chrome. Mount modals at the layout root, not deep in the tree.
• Debugging depth issues. Check the depth attribute/class applied to the modal wrapper and compare against your config; if scaling looks wrong, confirm the panel isn't accidentally flagged fullscreen.
• Missing assets. A modal that opens but has no animation or backdrop usually means published JS/CSS wasn't rebuilt after an upgrade — re-publish and clear compiled views.
• Extension points to prefer over forking: custom panel definitions, config overrides for depth/scale values, and open/close events/hooks. Overriding compiled CSS for scaling is fragile across patch releases like this one.