Merge remote-tracking branch 'origin/main' into modal

Author: github-actions[bot]

.claude/settings.local.json

@@ -11,7 +11,9 @@
       "Find",
       "Search",
       "WebSearch",
-      "WebFetch(*)"
+      "WebFetch(*)",
+      "Skill(browser-automation)",
+      "Skill(browser-automation:*)"
     ]
   }
 }

.github/workflows/test.yml

@@ -51,5 +51,14 @@ jobs:
       - name: Run type checking with ty
         run: uv run ty check .
 
+      - name: Install Playwright browsers
+        run: uv run playwright install --with-deps chromium
+
       - name: Run tests with pytest
+        env:
+          DB_HOST: localhost
+          DB_PORT: "5432"
+          DB_NAME: db
+          DB_USER: postgres
+          DB_PASSWORD: postgres
         run: uv run pytest tests/

docs/customization.qmd

@@ -247,6 +247,17 @@ graph.write_png('static/schema.png')
 
 To extend the database schema, define your own models in `utils/app/models.py` and import them in `utils/core/db.py` to make sure they are included in the `metadata` object in the `create_all` function.
 
+### Example application data model
+
+The template ships with an illustrative data model, `OrganizationResource`, in `utils/app/models.py`. This model demonstrates how to create an organization-scoped database table and is used by the dashboard to display example resources. It is **meant to be replaced** with your own application-specific models.
+
+To replace it:
+
+1. Edit `utils/app/models.py` — remove `OrganizationResource` and define your own SQLModel table classes. Any table class defined in this file will be automatically created in the database on startup.
+2. Update `routers/core/dashboard.py` — replace the `OrganizationResource` query and template context with your own data.
+3. Update `templates/dashboard/index.html` — replace the example resource list with your own application UI.
+4. Optionally add new permission values to `AppPermissions` in `utils/app/enums.py` if your models need custom permission checks. These are automatically registered alongside the core `ValidPermissions` during database setup.
+
 ### Database helpers
 
 Database operations are facilitated by helper functions in `utils/core/db.py` (for core logic) and `utils/app/` (for app-specific helpers). Key functions in the core utils include:
@@ -266,16 +277,20 @@ async def get_users(session: Session = Depends(get_session)):
 
 The session automatically handles transaction management, ensuring that database operations are atomic and consistent.
 
-There is also a helper method on the `User` model that checks if a user has a specific permission for a given organization. Its first argument must be a `ValidPermissions` enum value (from `utils/core/models.py`), and its second argument must be an `Organization` object or an `int` representing an organization ID:
+There is also a helper method on the `User` model that checks if a user has a specific permission for a given organization. Its first argument must be a `StrEnum` value (either from `ValidPermissions` in `utils/core/enums.py` or `AppPermissions` in `utils/app/enums.py`), and its second argument must be an `Organization` object or an `int` representing an organization ID:
 
 ```python
-permission = ValidPermissions.CREATE_ROLE
-organization = session.exec(select(Organization).where(Organization.name == "Acme Inc.")).first()
+from utils.core.enums import ValidPermissions
+from utils.app.enums import AppPermissions
+
+# Check a core permission
+user.has_permission(ValidPermissions.CREATE_ROLE, organization)
 
-user.has_permission(permission, organization)
+# Check an app-specific permission
+user.has_permission(AppPermissions.READ_ORGANIZATION_RESOURCES, organization)
 ```
 
-You can add custom permission enum values to the `ValidPermissions` enum in `utils/core/enums.py` (below the core permissions section) and validate that users have the necessary permissions before allowing them to modify organization data resources.
+Core permissions used by the template's built-in features are defined in `ValidPermissions` (`utils/core/enums.py`). To add your own app-specific permissions, define them in `AppPermissions` (`utils/app/enums.py`). Both enum types are automatically registered in the database during setup and work interchangeably with `User.has_permission()`.
 
 ### Cascade deletes
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-jinja2-postgres-webapp"
-version = "0.1.13"
+version = "0.1.14"
 description = "A template webapp with a pure-Python FastAPI backend, frontend templating with Jinja2, and a Postgres database to power user auth"
 readme = "README.md"
 package-mode = false
@@ -35,6 +35,7 @@ dev = [
     "ty>=0.0.21",
     "ruff>=0.15.5",
     "pytest-jinja-check[fastapi]>=1.0.2",
+    "pytest-playwright>=0.7.2",
 ]
 
 [tool.ty.rules]

routers/core/dashboard.py

@@ -1,8 +1,11 @@
-from typing import Optional
-from fastapi import APIRouter, Depends, Request
+from typing import Optional, List
+from fastapi import APIRouter, Depends, Request, Response
 from fastapi.templating import Jinja2Templates
-from utils.core.dependencies import get_user_with_relations
-from utils.core.models import User
+from sqlmodel import Session, select
+from utils.core.dependencies import get_user_with_relations, get_session
+from utils.core.models import User, Organization
+from utils.app.enums import AppPermissions
+from utils.app.models import OrganizationResource
 
 router = APIRouter(prefix="/dashboard", tags=["dashboard"])
 templates = Jinja2Templates(directory="templates")
@@ -14,10 +17,85 @@
 @router.get("/")
 async def read_dashboard(
     request: Request,
-    user: Optional[User] = Depends(get_user_with_relations)
+    user: User = Depends(get_user_with_relations),
+    session: Session = Depends(get_session),
 ):
+    organizations = user.organizations
+    selected_org: Optional[Organization] = None
+    resources: List[OrganizationResource] = []
+    can_read = False
+    can_write = False
+    can_delete = False
+
+    if organizations:
+        # Read selected org from cookie, fall back to first org
+        selected_org_id_str = request.cookies.get("selected_organization_id")
+        if selected_org_id_str:
+            try:
+                selected_org_id = int(selected_org_id_str)
+                selected_org = next(
+                    (o for o in organizations if o.id == selected_org_id), None
+                )
+            except ValueError:
+                pass
+
+        if not selected_org:
+            selected_org = organizations[0]
+
+        # Load organization resources for the selected org
+        if selected_org and selected_org.id is not None:
+            resources = list(session.exec(
+                select(OrganizationResource)
+                .where(OrganizationResource.organization_id == selected_org.id)
+                .order_by(OrganizationResource.created_at.desc())  # type: ignore[union-attr]
+            ).all())
+            can_read = user.has_permission(
+                AppPermissions.READ_ORGANIZATION_RESOURCES, selected_org
+            )
+            can_write = user.has_permission(
+                AppPermissions.WRITE_ORGANIZATION_RESOURCES, selected_org
+            )
+            can_delete = user.has_permission(
+                AppPermissions.DELETE_ORGANIZATION_RESOURCES, selected_org
+            )
+
     return templates.TemplateResponse(
         request,
         "dashboard/index.html",
-        {"user": user}
-    )
+        {
+            "user": user,
+            "organizations": organizations,
+            "selected_org": selected_org,
+            "resources": resources,
+            "can_read": can_read,
+            "can_write": can_write,
+            "can_delete": can_delete,
+        }
+    )
+
+
+@router.post("/select-organization/{org_id}")
+async def select_organization(
+    request: Request,
+    org_id: int,
+    user: User = Depends(get_user_with_relations),
+):
+    """Set the selected organization cookie and redirect back to dashboard."""
+    # Verify user is a member of this organization
+    org = next((o for o in user.organizations if o.id == org_id), None)
+    if not org:
+        # Fall back to dashboard without changing cookie
+        response = Response(status_code=200)
+        response.headers["HX-Redirect"] = str(request.url_for("read_dashboard"))
+        return response
+
+    response = Response(status_code=200)
+    response.set_cookie(
+        key="selected_organization_id",
+        value=str(org_id),
+        httponly=True,
+        samesite="strict",
+        max_age=60 * 60 * 24 * 365,  # 1 year
+    )
+    response.headers["HX-Redirect"] = str(request.url_for("read_dashboard"))
+    return response

routers/core/invitation.py

@@ -9,7 +9,8 @@
 from logging import getLogger
 
 from utils.core.dependencies import get_authenticated_user, get_optional_user, get_session
-from utils.core.models import User, Role, Account, Invitation, ValidPermissions, Organization
+from utils.core.models import User, Role, Account, Invitation, Organization
+from utils.core.enums import ValidPermissions
 from utils.core.invitations import send_invitation_email, process_invitation
 from exceptions.http_exceptions import (
     UserIsAlreadyMemberError,

routers/core/organization.py

@@ -9,6 +9,7 @@
 from utils.core.dependencies import get_authenticated_user, get_user_with_relations, get_session
 from utils.core.models import Organization, User, Role, Account, utc_now, Invitation
 from utils.core.enums import ValidPermissions
+from utils.app.enums import AppPermissions
 from exceptions.http_exceptions import (
     OrganizationNotFoundError, OrganizationNameTakenError,
     InsufficientPermissionsError, OrganizationSetupError,
@@ -71,6 +72,7 @@ async def read_organization(
             "user": user,
             "user_permissions": user_permissions,
             "ValidPermissions": ValidPermissions,
+            "all_permissions": list(ValidPermissions) + list(AppPermissions),
             "active_invitations": active_invitations
         }
     )

routers/core/role.py

@@ -9,7 +9,9 @@
 from sqlalchemy.orm import selectinload
 from sqlalchemy.exc import IntegrityError
 from utils.core.dependencies import get_authenticated_user, get_session
-from utils.core.models import Role, Permission, ValidPermissions, utc_now, User, DataIntegrityError, Organization
+from utils.core.models import Role, Permission, utc_now, User, DataIntegrityError, Organization
+from utils.core.enums import ValidPermissions
+from utils.app.enums import AppPermissions
 from exceptions.http_exceptions import InsufficientPermissionsError, InvalidPermissionError, RoleAlreadyExistsError, RoleNotFoundError, RoleHasUsersError, CannotModifyDefaultRoleError
 from routers.core.organization import router as organization_router
 from utils.core.htmx import is_htmx_request, append_toast
@@ -45,7 +47,7 @@ def create_role(
     request: Request,
     name: Annotated[str, Form(min_length=1, strip_whitespace=True, title="Role name", description="Name for the new role")],
     organization_id: int = Form(..., title="Organization ID", description="ID of the organization this role belongs to"),
-    permissions: List[ValidPermissions] = Form(default=[], title="Permissions", description="List of permissions to assign to this role"),
+    permissions: List[str] = Form(default=[], title="Permissions", description="List of permissions to assign to this role"),
     user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
 ):
@@ -94,6 +96,7 @@ def create_role(
                 "user": user,
                 "user_permissions": user_permissions,
                 "ValidPermissions": ValidPermissions,
+                "all_permissions": list(ValidPermissions) + list(AppPermissions),
             },
         )
         response.headers["HX-Trigger"] = "modalDismiss"
@@ -110,7 +113,7 @@ def update_role(
     id: int = Form(..., title="Role ID", description="ID of the role to update"),
     name: str = Form(..., min_length=1, strip_whitespace=True, title="Role name", description="Updated name for the role"),
     organization_id: int = Form(..., title="Organization ID", description="ID of the organization this role belongs to"),
-    permissions: List[ValidPermissions] = Form(default=[], title="Permissions", description="Updated list of permissions for this role"),
+    permissions: List[str] = Form(default=[], title="Permissions", description="Updated list of permissions for this role"),
     user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
 ):
@@ -132,8 +135,9 @@ def update_role(
         raise CannotModifyDefaultRoleError(action="update")
 
     # If any user-selected permissions are not valid, raise an error
+    all_valid = {str(p) for p in ValidPermissions} | {str(p) for p in AppPermissions}
     for permission in permissions:
-        if permission not in ValidPermissions:
+        if permission not in all_valid:
             raise InvalidPermissionError(permission)
 
     # Add any user-selected permissions that are not already associated with the role
@@ -184,6 +188,7 @@ def update_role(
                 "user": user,
                 "user_permissions": user_permissions,
                 "ValidPermissions": ValidPermissions,
+                "all_permissions": list(ValidPermissions) + list(AppPermissions),
             },
         )
         response.headers["HX-Trigger"] = "modalDismiss"
@@ -238,6 +243,7 @@ def delete_role(
                 "user": user,
                 "user_permissions": user_permissions,
                 "ValidPermissions": ValidPermissions,
+                "all_permissions": list(ValidPermissions) + list(AppPermissions),
             },
         )
         return append_toast(response, request, templates, "Role deleted successfully.")

routers/core/user.py

@@ -8,6 +8,7 @@
 from utils.core.dependencies import get_authenticated_user, get_user_with_relations, get_session
 from utils.core.images import validate_and_process_image, MAX_FILE_SIZE, MIN_DIMENSION, MAX_DIMENSION, ALLOWED_CONTENT_TYPES
 from utils.core.enums import ValidPermissions
+from utils.app.enums import AppPermissions
 from exceptions.http_exceptions import (
     InsufficientPermissionsError,
     UserNotFoundError,
@@ -192,6 +193,7 @@ def update_user_role(
                 "user": user,
                 "user_permissions": user_permissions,
                 "ValidPermissions": ValidPermissions,
+                "all_permissions": list(ValidPermissions) + list(AppPermissions),
             },
         )
         response.headers["HX-Trigger"] = "modalDismiss"
@@ -259,6 +261,7 @@ def remove_user_from_organization(
                 "user": user,
                 "user_permissions": user_permissions,
                 "ValidPermissions": ValidPermissions,
+                "all_permissions": list(ValidPermissions) + list(AppPermissions),
             },
         )
         return append_toast(response, request, templates, "User removed from organization.")

static/js/app.js

@@ -0,0 +1,67 @@
+// app.js — global utilities loaded with defer in <head>.
+// Because this script lives in <head> (outside <body>), it is never
+// re-processed during htmx hx-boost body swaps, which means the event
+// listeners registered here persist across page navigations.
+
+function showToast(message, level) {
+    level = level || 'success';
+    var container = document.getElementById('toast-container');
+    var wrapper = document.createElement('div');
+    wrapper.className = 'toast align-items-center text-bg-' + level + ' border-0 show';
+    wrapper.setAttribute('role', 'alert');
+    wrapper.setAttribute('aria-atomic', 'true');
+    wrapper.innerHTML =
+        '<div class="d-flex">' +
+            '<div class="toast-body">' + message + '</div>' +
+            '<button type="button" class="btn-close btn-close-white me-2 m-auto" data-bs-dismiss="toast" aria-label="Close"></button>' +
+        '</div>';
+    container.appendChild(wrapper);
+    setTimeout(function() { wrapper.remove(); }, 5000);
+}
+
+// For HTMX error responses, extract and apply OOB swaps (toasts) without
+// touching the main target. We parse the response HTML, find elements with
+// hx-swap-oob, and swap them in manually via htmx.process().
+document.body.addEventListener('htmx:beforeSwap', function(evt) {
+    if (evt.detail.xhr.status >= 400) {
+        evt.detail.shouldSwap = false;
+        evt.detail.isError = false;
+        var responseText = evt.detail.xhr.responseText;
+        if (responseText) {
+            var doc = new DOMParser().parseFromString(responseText, 'text/html');
+            var oobElements = doc.querySelectorAll('[hx-swap-oob]');
+            oobElements.forEach(function(el) {
+                var targetId = el.getAttribute('id');
+                if (targetId) {
+                    var existing = document.getElementById(targetId);
+                    if (existing) {
+                        existing.replaceWith(el);
+                        htmx.process(el);
+                    }
+                }
+            });
+        }
+    }
+});
+
+// Read flash cookie on page load
+(function() {
+    var raw = document.cookie.split('; ').find(function(c) { return c.startsWith('flash_message='); });
+    if (!raw) return;
+    var value = decodeURIComponent(raw.split('=').slice(1).join('='));
+    document.cookie = 'flash_message=; Max-Age=0; path=/';
+    try {
+        var flash = JSON.parse(value);
+        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');
+});