Laravel Hotwire Laravel Package

Product Decisions This Supports

• Build vs. buy for UI components: This package provides a suite of server-rendered Blade components (Modal, Sheet, Drawer, Sidebar, Video Embed) with Hotwire integration, letting the team avoid building and maintaining custom UI primitives. The 0.83.0 release strengthens the “buy” case for overlay workflows: one layout-level host can now serve multiple independent and nested openings—eliminating application-authored clone IDs and per-form duplicate hosts—while server-side helpers (response()->modal()/sheet()/drawer()->open(...)) cover opening, returning content, and instance-scoped closing. That is a meaningful amount of interaction plumbing we would otherwise own.
• Feature roadmap for multi-step and contextual workflows: Contextual returns (returnFromOverlay() paired with <hw:overlay-return> and the opener’s overlay-return prop) mean we can ship edit-in-place, nested create flows, and partial-update dialogs where validation errors and returned HTML land in the correct parent region. PMs can scope richer in-context editing into roadmap items that previously looked like they required a custom SPA-style renderer.
• Reliability expectations for concurrent overlays: Explicit instance-scoped closing (closeOverlay($origin)) with late responses unable to affect a later opening, plus safe failure when a return destination is replaced, converts a class of “stale modal overwrote my form” bugs into handled behavior. This supports committing the component library to critical flows like checkout-adjacent forms and admin editing.
• Upgrade and maintenance strategy: Because overlays are now server-composed, correctness increasingly depends on staying current. The 0.83.0 upgrade removes modal-auto-close, replaces marker appends with closeOverlay(), requires concrete instance IDs for frame-backed openings (use $request->overlayOrigin() and guard null), and requires rebuilding published controller assets. PMs should budget an upgrade spike for any existing overlay integrations rather than treating this as a drop-in minor bump—and should note the package moved 0.81 → 0.83 with a breaking change, so pinning and scheduled upgrades remain necessary.
• Accessibility as a shipped capability, not a backlog item: Opt-in error-focus on <hw:form> focuses the first eligible invalid control after validation, including delayed Rich Text initialization, and focus returns to the Dropdown/Popover trigger when an overlay’s opener is no longer focusable. These are recurring accessibility audit findings we can close without dedicated engineering work.
• Standardization and design system adoption: Per-opening size and side, with response metadata taking precedence over loading hints without mutating other instances, lets design own presentation variants while keeping a single host pattern across the app. Presets and app-level overrides continue to support consistent patterns.
• Architecture boundary decision: The release explicitly declines to manage return rendering—host:, result:, and package-managed renderers are unsupported; composition happens via application-owned fragments or native Turbo Frames. That is a deliberate trade: less magic, more predictable debugging, but our team owns fragment composition. PMs should treat this as a design constraint when estimating overlay-heavy features.

When to Consider This Package

• Adopt when: Your application is built on Laravel and uses (or plans to use) Hotwire/Turbo with server-rendered Blade components. You have overlay-heavy UX (dialogs, sheets, drawers, nested forms) and want one reusable host plus server-driven open/return/close rather than hand-rolled JavaScript. You want accessible focus and validation behavior, JS-free video embeds, and selective preset bundling with safe regeneration.
• Look elsewhere when: You are not using Laravel or Hotwire (e.g., React/Vue/Svelte frontends), or you need deeply custom UI that cannot be extended via presets and overrides. Also look elsewhere if you require a stable 1.0+ API with long-term support commitments—0.83.0 removes modal-auto-close and changes frame-backed overlay identity, which is real migration work. Existing integrations that depend on package-managed return renderers (host:, result:) or on the previous static overlay close semantics will need rework; teams without bandwidth for that should defer. Static overlays now close by root ID, and stream openings require explicit origin: and source: when a fragment contains a form—worth verifying against current markup before committing.

How to Pitch It (Stakeholders)

• To executives: This package keeps our UI work server-rendered and JavaScript-light, which protects page performance and accessibility while shortening delivery on common patterns. The new release makes overlay-based workflows—multi-step forms, in-context editing, nested creation—reusable from a single host instead of custom per screen, reducing both build cost and a known class of stale-state bugs. The trade-off is that we must schedule an upgrade pass: one legacy overlay mechanism was removed and some interaction IDs changed. That is bounded, documented work, and staying current lowers long-term risk more than skipping it.
• To engineering: 0.83.0 adds reusable Modal/Sheet/Drawer hosts supporting multiple independent and nested openings from one layout host, with per-opening size/side where response metadata overrides loading hints without affecting other instances. Server-driven flows use response()->modal()/sheet()/drawer()->open(...), returnFromOverlay($origin, $content) targeting <hw:overlay-return>, and instance-scoped closeOverlay($origin); late responses cannot affect later openings and replaced return destinations fail safely. Validation gains opt-in error-focus on <hw:form> (handles delayed Rich Text init) and focus returns to Dropdown/Popover triggers when the original opener is unfocusable. Upgrade notes: modal-auto-close removed—replace marker appends with closeOverlay(), delete any published controller copy, rebuild assets; frame-backed openings now have concrete instance IDs, so use $request->overlayOrigin() and guard null for actions also serving page requests; static overlays close by root ID; stream openings need explicit origin: and source: for fragments containing forms. Do not expect package-managed return renderers. Tiptap dependency group moved to 3.32.0 with dev tooling refreshed.
• To design/UX: One host now supports multiple simultaneous and nested overlays with per-opening size and side, so layout patterns stay consistent while individual surfaces vary. Focus and error handling improve by default—first invalid field receives focus, and focus falls back gracefully when an opener disappears—with consistent, accessible components and preset bundles to enforce design system usage.