Bugfixes for modal cleanup

chriscarrollsmith · chriscarrollsmith · commit b71c725f0e5b · 2026-03-12T19:28:02.000-04:00
diff --git a/routers/core/invitation.py b/routers/core/invitation.py
@@ -139,6 +139,7 @@ async def create_invitation(
             "organization/partials/invitations_list.html",
             {"active_invitations": active_invitations},
         )
+        response.headers["HX-Trigger"] = "modalDismiss"
         return append_toast(response, request, templates, "Invitation sent successfully.")
     return RedirectResponse(url=f"/organizations/{organization_id}", status_code=303)
 
diff --git a/routers/core/role.py b/routers/core/role.py
@@ -96,6 +96,7 @@ def create_role(
                 "ValidPermissions": ValidPermissions,
             },
         )
+        response.headers["HX-Trigger"] = "modalDismiss"
         return append_toast(response, request, templates, "Role created successfully.")
     return RedirectResponse(
         url=organization_router.url_path_for("read_organization", org_id=organization_id),
@@ -185,6 +186,7 @@ def update_role(
                 "ValidPermissions": ValidPermissions,
             },
         )
+        response.headers["HX-Trigger"] = "modalDismiss"
         return append_toast(response, request, templates, "Role updated successfully.")
     return RedirectResponse(
         url=organization_router.url_path_for("read_organization", org_id=organization_id),
diff --git a/routers/core/user.py b/routers/core/user.py
@@ -109,6 +109,7 @@ async def update_profile(
                 "allowed_formats": list(ALLOWED_CONTENT_TYPES.keys()),
             },
         )
+        response.headers["HX-Trigger"] = "profileUpdated"
         return append_toast(response, request, templates, "Profile updated successfully.")
     return RedirectResponse(url=router.url_path_for("read_profile"), status_code=303)
 
@@ -193,6 +194,7 @@ def update_user_role(
                 "ValidPermissions": ValidPermissions,
             },
         )
+        response.headers["HX-Trigger"] = "modalDismiss"
         return append_toast(response, request, templates, "User role updated successfully.")
     return RedirectResponse(
         url=organization_router.url_path_for("read_organization", org_id=organization_id),
diff --git a/templates/base.html b/templates/base.html
@@ -93,6 +93,15 @@
             if (flash && flash.message) showToast(flash.message, flash.level);
         } catch(e) {}
     })();
+    // Global handler: when a server response includes HX-Trigger: modalDismiss,
+    // clean up any Bootstrap modal backdrop left behind by OOB swaps that
+    // replaced the modal element before afterRequest could call .hide().
+    document.body.addEventListener('modalDismiss', function() {
+        document.querySelectorAll('.modal-backdrop').forEach(function(el) { el.remove(); });
+        document.body.classList.remove('modal-open');
+        document.body.style.removeProperty('overflow');
+        document.body.style.removeProperty('padding-right');
+    });
     </script>
     {% block extra_scripts %}{% endblock %}
 </body>
diff --git a/templates/organization/modals/edit_organization_modal.html b/templates/organization/modals/edit_organization_modal.html
@@ -4,8 +4,7 @@
   <div class="modal-dialog">
     <div class="modal-content">
       <form method="POST" action="{{ url_for('update_organization', org_id=organization.id) }}"
-            hx-post="{{ url_for('update_organization', org_id=organization.id) }}"
-            hx-on::after-request="if(event.detail.successful) { bootstrap.Modal.getInstance(document.getElementById('editOrganizationModal'))?.hide(); }">
+            hx-post="{{ url_for('update_organization', org_id=organization.id) }}">
         <div class="modal-header">
           <h5 class="modal-title" id="editOrganizationModalLabel">Edit Organization</h5>
           <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
diff --git a/templates/organization/modals/members_card.html b/templates/organization/modals/members_card.html
@@ -104,8 +104,7 @@ <h4>Pending Invitations</h4>
       <form method="POST" action="{{ url_for('create_invitation') }}"
             hx-post="{{ url_for('create_invitation') }}"
             hx-target="#members-card-content"
-            hx-swap="innerHTML"
-            hx-on::after-request="if(event.detail.successful) { bootstrap.Modal.getInstance(document.getElementById('inviteMemberModal'))?.hide(); }">
+            hx-swap="innerHTML">
         <div class="modal-header">
           <h5 class="modal-title" id="inviteMemberModalLabel">Invite New Member</h5>
           <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
@@ -146,8 +145,7 @@ <h5 class="modal-title" id="inviteMemberModalLabel">Invite New Member</h5>
           <form method="POST" action="{{ url_for('update_user_role') }}"
                 hx-post="{{ url_for('update_user_role') }}"
                 hx-target="#members-card-content"
-                hx-swap="innerHTML"
-                hx-on::after-request="if(event.detail.successful) { bootstrap.Modal.getInstance(document.getElementById('editUserRoleModal{{ member.id }}'))?.hide(); }">
+                hx-swap="innerHTML">
             <div class="modal-header">
               <h5 class="modal-title" id="editUserRoleModalLabel{{ member.id }}">Edit Roles for {{ member.name }}</h5>
               <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
diff --git a/templates/organization/modals/roles_card.html b/templates/organization/modals/roles_card.html
@@ -83,8 +83,7 @@
       <form method="POST" action="{{ url_for('create_role') }}"
             hx-post="{{ url_for('create_role') }}"
             hx-target="#roles-card-content"
-            hx-swap="innerHTML"
-            hx-on::after-request="if(event.detail.successful) { bootstrap.Modal.getInstance(document.getElementById('createRoleModal'))?.hide(); }">
+            hx-swap="innerHTML">
         <div class="modal-header">
           <h5 class="modal-title" id="createRoleModalLabel">Create New Role</h5>
           <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
@@ -131,8 +130,7 @@ <h5 class="modal-title" id="createRoleModalLabel">Create New Role</h5>
           <form method="POST" action="{{ url_for('update_role') }}"
                 hx-post="{{ url_for('update_role') }}"
                 hx-target="#roles-card-content"
-                hx-swap="innerHTML"
-                hx-on::after-request="if(event.detail.successful) { bootstrap.Modal.getInstance(document.getElementById('editRoleModal{{ role.id }}'))?.hide(); }">
+                hx-swap="innerHTML">
             <div class="modal-header">
               <h5 class="modal-title" id="editRoleModalLabel{{ role.id }}">Edit Role: {{ role.name }}</h5>
               <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
diff --git a/templates/organization/partials/members_table.html b/templates/organization/partials/members_table.html
@@ -90,8 +90,7 @@ <h4>Pending Invitations</h4>
           <form method="POST" action="{{ url_for('update_user_role') }}"
                 hx-post="{{ url_for('update_user_role') }}"
                 hx-target="#members-card-content"
-                hx-swap="innerHTML"
-                hx-on::after-request="if(event.detail.successful) { bootstrap.Modal.getInstance(document.getElementById('editUserRoleModal{{ member.id }}'))?.hide(); }">
+                hx-swap="innerHTML">
             <div class="modal-header">
               <h5 class="modal-title" id="editUserRoleModalLabel{{ member.id }}">Edit Roles for {{ member.name }}</h5>
               <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
diff --git a/templates/organization/partials/roles_table.html b/templates/organization/partials/roles_table.html
@@ -66,8 +66,7 @@
           <form method="POST" action="{{ url_for('update_role') }}"
                 hx-post="{{ url_for('update_role') }}"
                 hx-target="#roles-card-content"
-                hx-swap="innerHTML"
-                hx-on::after-request="if(event.detail.successful) { bootstrap.Modal.getInstance(document.getElementById('editRoleModal{{ role.id }}'))?.hide(); }">
+                hx-swap="innerHTML">
             <div class="modal-header">
               <h5 class="modal-title" id="editRoleModalLabel{{ role.id }}">Edit Role: {{ role.name }}</h5>
               <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
diff --git a/templates/users/partials/profile_form.html b/templates/users/partials/profile_form.html
@@ -3,8 +3,7 @@
       hx-post="{{ url_for('update_profile') }}"
       hx-target="#profile-display"
       hx-swap="innerHTML"
-      hx-encoding="multipart/form-data"
-      hx-on::after-request="if(event.detail.successful) { document.getElementById('edit-profile').style.display='none'; document.getElementById('basic-info').style.display='block'; }">
+      hx-encoding="multipart/form-data">
     <div class="mb-3">
         <label for="name" class="form-label">Name</label>
         <input type="text" class="form-control" id="name" name="name" value="{{ user.name }}">
diff --git a/templates/users/profile.html b/templates/users/profile.html
@@ -39,8 +39,7 @@ <h1 class="mb-4">User Profile</h1>
                   hx-post="{{ url_for('update_profile') }}"
                   hx-target="#profile-display"
                   hx-swap="innerHTML"
-                  hx-encoding="multipart/form-data"
-                  hx-on::after-request="if(event.detail.successful) { document.getElementById('edit-profile').style.display='none'; document.getElementById('basic-info').style.display='block'; }">
+                  hx-encoding="multipart/form-data">
                 <div class="mb-3">
                     <label for="name" class="form-label">Name</label>
                     <input type="text" class="form-control" id="name" name="name" value="{{ user.name }}">
@@ -131,7 +130,7 @@ <h1 class="mb-4">User Profile</h1>
     function toggleEditProfile() {
         var basicInfo = document.getElementById('basic-info');
         var editProfile = document.getElementById('edit-profile');
-        
+
         if (basicInfo.style.display === 'none') {
             basicInfo.style.display = 'block';
             editProfile.style.display = 'none';
@@ -141,6 +140,15 @@ <h1 class="mb-4">User Profile</h1>
         }
     }
 
+    // After a successful profile update the server sends an HX-Trigger
+    // header with "profileUpdated".  Toggle back to the display card.
+    // (We cannot use hx-on::after-request on the form because the OOB
+    // swap for #profile-form replaces it before afterRequest fires.)
+    document.body.addEventListener('profileUpdated', function() {
+        document.getElementById('edit-profile').style.display = 'none';
+        document.getElementById('basic-info').style.display = 'block';
+    });
+
     document.getElementById('avatar_file').addEventListener('change', function(e) {
         const file = e.target.files[0];
         if (!file) return;
diff --git a/tests/test_htmx.py b/tests/test_htmx.py
@@ -691,6 +691,23 @@ def test_update_profile_htmx_includes_success_toast(auth_client):
     assert "toast" in response.text
 
 
+def test_update_profile_htmx_triggers_profile_updated_event(auth_client):
+    """The response must include an HX-Trigger header so the client can
+    toggle display of the basic-info / edit-profile cards.  Using
+    hx-on::after-request on the form is unreliable because the OOB swap
+    for #profile-form replaces the form element before afterRequest fires
+    (HTMX 2.0 fires afterRequest AFTER the swap)."""
+    response = auth_client.post(
+        "/user/update",
+        data={"name": "Trigger Name"},
+        headers=htmx_headers(),
+    )
+    assert response.status_code == 200
+    trigger = response.headers.get("HX-Trigger")
+    assert trigger is not None, "Missing HX-Trigger response header"
+    assert "profileUpdated" in trigger
+
+
 def test_create_role_htmx_includes_success_toast(auth_client_owner, test_organization):
     response = auth_client_owner.post(
         "/roles/create",
@@ -743,6 +760,93 @@ def test_update_role_htmx_includes_success_toast(auth_client_owner, test_organiz
     assert "Role updated successfully" in response.text
 
 
+def test_update_role_htmx_triggers_modal_cleanup(auth_client_owner, test_organization, session):
+    """The response must include an HX-Trigger header so the client can
+    dismiss the Bootstrap modal and its backdrop.  The OOB swap for
+    #role-modals-container replaces the modal element before afterRequest
+    fires, leaving the backdrop stuck on screen."""
+    from utils.core.models import Role
+    custom_role = Role(name="TriggerRole", organization_id=test_organization.id)
+    session.add(custom_role)
+    session.commit()
+    session.refresh(custom_role)
+
+    response = auth_client_owner.post(
+        "/roles/update",
+        data={
+            "id": str(custom_role.id),
+            "name": "TriggerRenamed",
+            "organization_id": str(test_organization.id),
+        },
+        headers=htmx_headers(),
+    )
+    assert response.status_code == 200
+    trigger = response.headers.get("HX-Trigger")
+    assert trigger is not None, "Missing HX-Trigger response header"
+    assert "modalDismiss" in trigger
+
+
+def test_create_role_htmx_triggers_modal_cleanup(auth_client_owner, test_organization):
+    """create_role must send HX-Trigger: modalDismiss to close the
+    create-role Bootstrap modal after the swap."""
+    response = auth_client_owner.post(
+        "/roles/create",
+        data={
+            "name": "ModalCleanupRole",
+            "organization_id": str(test_organization.id),
+        },
+        headers=htmx_headers(),
+    )
+    assert response.status_code == 200
+    trigger = response.headers.get("HX-Trigger")
+    assert trigger is not None, "Missing HX-Trigger response header"
+    assert "modalDismiss" in trigger
+
+
+def test_create_invitation_htmx_triggers_modal_cleanup(
+    auth_client_owner, test_organization, member_role, mock_resend_send
+):
+    """create_invitation must send HX-Trigger: modalDismiss to close
+    the invite-member Bootstrap modal after the swap."""
+    response = auth_client_owner.post(
+        "/invitations/",
+        data={
+            "invitee_email": "modaldismiss@example.com",
+            "role_id": str(member_role.id),
+            "organization_id": str(test_organization.id),
+        },
+        headers=htmx_headers(),
+    )
+    assert response.status_code == 200
+    trigger = response.headers.get("HX-Trigger")
+    assert trigger is not None, "Missing HX-Trigger response header"
+    assert "modalDismiss" in trigger
+
+
+def test_update_user_role_htmx_triggers_modal_cleanup(
+    auth_client_owner, org_member_user, test_organization, member_role
+):
+    """update_user_role must send HX-Trigger: modalDismiss to close
+    the edit-user-role Bootstrap modal after the swap."""
+    assert org_member_user.id is not None
+    assert test_organization.id is not None
+    assert member_role.id is not None
+
+    response = auth_client_owner.post(
+        "/user/role/update",
+        data={
+            "user_id": str(org_member_user.id),
+            "organization_id": str(test_organization.id),
+            "roles": [str(member_role.id)],
+        },
+        headers=htmx_headers(),
+    )
+    assert response.status_code == 200
+    trigger = response.headers.get("HX-Trigger")
+    assert trigger is not None, "Missing HX-Trigger response header"
+    assert "modalDismiss" in trigger
+
+
 def test_create_invitation_htmx_includes_success_toast(
     auth_client_owner, test_organization, member_role, mock_resend_send
 ):
@@ -788,3 +892,30 @@ def test_remove_user_htmx_includes_success_toast(
     )
     assert response.status_code == 200
     assert "User removed from organization" in response.text
+
+
+# ---------------------------------------------------------------------------
+# 7 — Architectural guard: ban hx-on::after-request in templates
+# ---------------------------------------------------------------------------
+
+def test_no_templates_use_hx_on_after_request():
+    """In HTMX 2.0 afterRequest fires AFTER the swap, so any handler
+    on an element that is replaced by an OOB swap will silently fail.
+    Use HX-Trigger response headers instead."""
+    import pathlib
+    import re
+
+    # Match the attribute in HTML tags, not in JS comments or prose.
+    attr_pattern = re.compile(r'hx-on::after-request=|hx-on:htmx:after-request=')
+
+    templates_dir = pathlib.Path(__file__).resolve().parent.parent / "templates"
+    violations = []
+    for path in templates_dir.rglob("*.html"):
+        text = path.read_text()
+        if attr_pattern.search(text):
+            violations.append(str(path.relative_to(templates_dir)))
+
+    assert violations == [], (
+        f"Templates must not use hx-on::after-request (unreliable in HTMX 2.0). "
+        f"Use HX-Trigger response headers instead. Violations: {violations}"
+    )

Original file line number	Diff line number	Diff line change
`@@ -139,6 +139,7 @@ async def create_invitation(`
`139`	`139`	`"organization/partials/invitations_list.html",`
`140`	`140`	`{"active_invitations": active_invitations},`
`141`	`141`	`)`
	`142`	`+ response.headers["HX-Trigger"] = "modalDismiss"`
`142`	`143`	`return append_toast(response, request, templates, "Invitation sent successfully.")`
`143`	`144`	`return RedirectResponse(url=f"/organizations/{organization_id}", status_code=303)`
`144`	`145`
Original file line number	Diff line number	Diff line change
`@@ -109,6 +109,7 @@ async def update_profile(`
`109`	`109`	`"allowed_formats": list(ALLOWED_CONTENT_TYPES.keys()),`
`110`	`110`	`},`
`111`	`111`	`)`
	`112`	`+ response.headers["HX-Trigger"] = "profileUpdated"`
`112`	`113`	`return append_toast(response, request, templates, "Profile updated successfully.")`
`113`	`114`	`return RedirectResponse(url=router.url_path_for("read_profile"), status_code=303)`
`114`	`115`
`@@ -193,6 +194,7 @@ def update_user_role(`
`193`	`194`	`"ValidPermissions": ValidPermissions,`
`194`	`195`	`},`
`195`	`196`	`)`
	`197`	`+ response.headers["HX-Trigger"] = "modalDismiss"`
`196`	`198`	`return append_toast(response, request, templates, "User role updated successfully.")`
`197`	`199`	`return RedirectResponse(`
`198`	`200`	`url=organization_router.url_path_for("read_organization", org_id=organization_id),`