DEP-263: Add dynamic page titles based on route handles

Author: NatSquared

CHANGELOG.MD

@@ -1,6 +1,13 @@
+## June 22, 2026
+
+- **Feature** Added dynamic tab titles based on the current chain of route matches [🎟️ DEP-263](https://citz-gdx.atlassian.net/browse/DEP-263)
+  - Updated the DocumentTitle component to dynamically generate the browser tab title based on the current route matches and their associated handles, similar to the automatic breadcrumb system. This ensures that the page title reflects the current context of the application, including engagement titles, page names, or other relevant data.
+    - Minor reorganization to some routes to ensure they display correctly in all situations
+  - Added documentation for hooking into the `handle` / `useMatches` ecosystem as it is used in DEP.
+
 ## June 16, 2026
 
-- **Feature** Merged engagement slug into engagement requests [🎟️ DEP-265](https://citz-gdx.atlassian.net/browse/DEP-265)
+- **Feature** Merged engagement slug into engagement requests [ DEP-265](https://citz-gdx.atlassian.net/browse/DEP-265)
   - Removed the EngagementSlug model, schema, and resource from the API, as they are no longer needed.
   - Updated the Engagement model to include a `slug` field, which is now used to store the engagement slug directly in the engagement record.
   - Engagements can now be fetched by slug, rather than fetching the slug then fetching the engagement by ID. This hastens the process of retrieving engagement data based on the slug.

docs/React_Route_Handles.md

@@ -0,0 +1,83 @@
+## Route Handles in DEP
+
+In our React Router setup, we utilize the `handle` property on route definitions to provide additional metadata that can be used throughout our application. This is particularly useful for features like breadcrumb generation and dynamic document titles.
+
+### Setting up a route handle
+
+When defining a route, you can include a `handle` property that returns an object with a `crumb` function. This function should return an object containing at least a `name` property, which will be used for breadcrumb display and document title generation. You can also include an optional `link` property for breadcrumb navigation and an `isIndex` property to indicate if the route is an index page. You can return a separate `title` property if you want to use a different string inside the document title than the breadcrumb name.
+
+```tsx
+{
+    handle: {
+        crumb: () => ({ name: 'Engagements', title: 'All Engagements', link: getPath(ROUTES.ENGAGEMENT_LISTING)}),
+    },
+}
+
+// Result:
+//   - Page title: "All Engagements | DEP"
+//   - Breadcrumb: "Home > Engagements" (clickable link to the listing page)
+```
+
+### Using loader data in route handles
+
+If your breadcrumb name needs to be dynamic based on loader data, your crumb function can expect a `data` parameter, which will be the RESOLVED data returned from the route's loader. This allows you to generate breadcrumb names that reflect the specific content being viewed. This data will never be a promise, as it is processed by the page before the crumb function is called.
+
+```tsx
+{
+    handle: {
+        crumb: (data) => ({ name: data?.engagement?.title || 'Engagement Details' }),
+    },
+}
+// Result:
+//   - Page title: "<engagement title> | DEP"
+//   - Breadcrumb: "Home > Engagements > <engagement title>"
+```
+
+### Excluding index pages from document titles
+
+If you want to exclude a route from being included in the document title, you can set the `isIndex` property to `true` in the crumb object. This is useful for routes that serve as index pages for their parent routes, such as a listing page that should not appear in the document title when viewing an individual item.
+
+For example, if you had a page `/products/:productId` that shows details for a specific product, you might have a parent route `/products` that lists all products. You would want the breadcrumb to show "Products > Product Name", but the document title should just be "Product Name". In this case, you would set `isIndex: true` on the crumb for the `/products` route.
+
+```tsx
+return (
+    <LazyRoute
+        path="products"
+        handle={{
+            allowedRoles: [USER_ROLES.EDIT_ENGAGEMENT],
+            crumb: (data?: { engagement?: { id?: number } }) => ({
+                name: 'Products',
+                isIndex: true,
+            }),
+        }}
+    >
+        <LazyRoute
+            index
+            ComponentLazy={...}
+            handle={{
+                crumb: (data) => ({ name: data?.product?.name || 'Product Details' }),
+            }}
+        />
+    </LazyRoute>
+)
+
+// Result:
+//   - Breadcrumb: "Home > Products > Product Name"
+//   - Page title: "Product Name | DEP"
+```
+
+### Hooking into the crumb system
+
+If you want to design a component that can leverage the crumb system for consistent breadcrumb and title generation, you can use the `useMatches` hook from React Router to access the current route matches and their associated handles. This allows you to dynamically pull route tree information and generate breadcrumbs or titles based on the current route context.
+
+```tsx
+import { useMatches } from "react-router";
+
+const matches = useMatches();
+const crumbs = matches
+  .map((match) => match.handle?.crumb?.(match.data))
+  .filter((crumb) => crumb?.name && !crumb?.isIndex);
+
+// Example of generating a breadcrumb-style path from the current page:
+const my_generated_path = crumbs.map((crumb) => crumb.name).join(" > ");
+```

web/src/DocumentTitle.tsx

@@ -1,12 +1,68 @@
-import React from 'react';
+import React, { useEffect } from 'react';
 import { Helmet } from 'react-helmet-async';
 import { TenantState } from 'reduxSlices/tenantSlice';
 import { useAppSelector } from './hooks';
+import { useMatches } from 'react-router';
+import { BreadcrumbProps, UIMatchWithCrumb } from 'components/common/Navigation/Breadcrumb';
+
+const truncate = (str: string, maxLength: number) => {
+    if (str.length <= maxLength) return str;
+    return str.slice(0, maxLength - 1) + '…';
+};
+
 const DocumentTitle = () => {
     const tenant: TenantState = useAppSelector((state) => state.tenant);
+    // Reverse list to prioritize the most specific route matches for title
+    const matches = useMatches().reverse() as UIMatchWithCrumb[];
+    const [pageTitle, setPageTitle] = React.useState(tenant.title);
+
+    const getResolvedCrumbs = async (matches: UIMatchWithCrumb[]) => {
+        return await Promise.all(
+            matches.map(async (match) => {
+                if (match.handle?.crumb) {
+                    try {
+                        const data = match.loaderData;
+                        const resolvedCrumb = await match.handle.crumb(data);
+                        return resolvedCrumb;
+                    } catch {
+                        return null;
+                    }
+                }
+                return null;
+            }),
+        ).then((crumbs) => crumbs.filter((crumb): crumb is BreadcrumbProps => crumb !== null));
+    };
+
+    useEffect(() => {
+        let cancelled = false;
+
+        const resolveTitle = async () => {
+            const crumbs = await getResolvedCrumbs(matches);
+            if (cancelled) return;
+            console.log('Resolved crumbs for title:', crumbs);
+            const filteredCrumbs = crumbs
+                // Exclude crumbs that are marked as index pages UNLESS they are the current page
+                .filter((crumb, index) => (crumb?.title ?? crumb?.name) && (index == 0 || !crumb?.isIndex))
+                .map((crumb) => truncate(crumb.title ?? crumb.name, 40)); // Limit individual crumb length to prevent excessively long titles
+            const title = filteredCrumbs.length > 0 ? filteredCrumbs.join(' | ') : tenant.title;
+            const truncatedTitle = truncate(title, 65); // Limit total title length to prevent browser truncation
+            if (truncatedTitle == title) {
+                setPageTitle(title + ' | ' + 'Digital Engagement Platform');
+            } else {
+                setPageTitle(truncatedTitle + ' | ' + 'DEP');
+            }
+        };
+
+        resolveTitle();
+
+        return () => {
+            cancelled = true;
+        };
+    }, [matches, tenant.title]);
+
     return (
         <Helmet>
-            <title>{tenant.title}</title>
+            <title>{pageTitle}</title>
         </Helmet>
     );
 };

web/src/components/common/Navigation/Breadcrumb.tsx

@@ -6,9 +6,13 @@ import { UIMatch, useMatches } from 'react-router';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import { faHome } from '@fortawesome/pro-regular-svg-icons';
 
-type BreadcrumbProps = {
+export type BreadcrumbProps = {
     name: string;
     link?: string;
+    // If true, this crumb will be considered an index page for its parent and will not be used
+    // when generating the page title, though the breadcrumb will still render unaffected.
+    title?: string; // Optional custom title for document title generation, if different from the breadcrumb name
+    isIndex?: boolean;
 };
 
 /**
@@ -58,14 +62,15 @@ export const BreadcrumbTrail: React.FC<{ crumbs: BreadcrumbProps[]; smallScreenO
     );
 };
 
-type UICrumbFunction = (data: unknown) => Promise<BreadcrumbProps> | BreadcrumbProps;
+export type UICrumbFunction = (data: unknown) => Promise<BreadcrumbProps> | BreadcrumbProps;
 
-interface UIRouteHandle {
+export interface UIRouteHandle {
     crumb?: UICrumbFunction;
+    excludeFromTitle?: boolean; // If true, this route's crumb will be excluded from the document title generation
 }
 
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-interface UIMatchWithCrumb extends UIMatch<unknown, UIRouteHandle> {}
+export interface UIMatchWithCrumb extends UIMatch<unknown, UIRouteHandle> {}
 
 /**
  * Automatically generates breadcrumbs based on the `handle.crumb` function of the current route and its parents.

web/src/components/engagement/dashboard/comment/CommentsBlock.tsx

@@ -1,14 +1,11 @@
 import React, { useContext } from 'react';
 import { Grid2 as Grid, Paper, Skeleton } from '@mui/material';
-import { useNavigate, useParams } from 'react-router';
+import { useLocation, useParams } from 'react-router';
 import { Link } from 'components/common/Navigation';
 import { Button } from 'components/common/Input/Button';
 import { CommentViewContext } from './CommentViewContext';
 import { Heading4 } from 'components/common/Typography/Headings';
 import CommentTable from './CommentTable';
-import { useAppSelector, useAppDispatch } from 'hooks';
-import { SubmissionStatus } from 'constants/engagementStatus';
-import { openNotificationModal } from 'services/notificationModalService/notificationModalSlice';
 import { useAppTranslation } from 'hooks';
 import { faFileChartPie } from '@fortawesome/pro-regular-svg-icons';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
@@ -22,11 +19,9 @@ interface CommentsBlockProps {
 export const CommentsBlock: React.FC<CommentsBlockProps> = ({ dashboardType }) => {
     const { t: translate } = useAppTranslation();
     const { slug, language } = useParams();
+    const location = useLocation();
     const { engagement, isEngagementLoading } = useContext(CommentViewContext);
-    const navigate = useNavigate();
-    const dispatch = useAppDispatch();
-    const canAccessDashboard = useAppSelector((state) => state.user.roles.includes('access_dashboard'));
-    const isLoggedIn = useAppSelector((state) => state.user.authentication.authenticated);
+    const isAdminPath = location.pathname === '/manage' || location.pathname.startsWith('/manage/');
     const publicEngagementLink = getPath(R.PUBLIC_ENGAGEMENT_BY_SLUG, {
         slug: slug ?? '',
         language: language ?? sessionStorage.getItem('languageId') ?? AppConfig.language.defaultLanguageId,
@@ -42,36 +37,7 @@ export const CommentsBlock: React.FC<CommentsBlockProps> = ({ dashboardType }) =
         engagementId: engagementId ?? '',
         dashboardType,
     });
-
-    const handleViewDashboard = () => {
-        /* check to ensure that users with role access_dashboard can access the dashboard while engagement not closed*/
-        if (canAccessDashboard) {
-            if (!engagementId && isLoggedIn) return;
-            navigate(isLoggedIn ? engagementDashboardLink : publicEngagementDashboardLink);
-            return;
-        }
-
-        /* check to ensure that all other users can access the dashboard only after the engagement is closed*/
-        if (engagement?.submission_status !== SubmissionStatus.Closed) {
-            dispatch(
-                openNotificationModal({
-                    open: true,
-                    data: {
-                        header: translate('commentDashboard.block.notification.header'),
-                        subText: [{ text: translate('commentDashboard.block.notification.text') }],
-                    },
-                    type: 'update',
-                }),
-            );
-            return;
-        }
-
-        if (isLoggedIn) {
-            if (!engagementId) return;
-            navigate(engagementDashboardLink);
-        }
-        navigate(publicEngagementDashboardLink);
-    };
+    const dashboardURL = isAdminPath ? engagementDashboardLink : publicEngagementDashboardLink;
 
     if (isEngagementLoading || !engagement) {
         return <Skeleton width="100%" height="40em" />;
@@ -80,7 +46,7 @@ export const CommentsBlock: React.FC<CommentsBlockProps> = ({ dashboardType }) =
     return (
         <>
             <Grid size={12} container direction="row" justifyContent="flex-end" paddingBottom={'8px'}>
-                <Link to={isLoggedIn ? adminEngagementViewLink : publicEngagementLink} style={{ color: '#1A5A96' }}>
+                <Link to={isAdminPath ? adminEngagementViewLink : publicEngagementLink} sx={{ color: 'text.link' }}>
                     {translate('commentDashboard.block.engagementLink')}
                 </Link>
             </Grid>
@@ -100,7 +66,7 @@ export const CommentsBlock: React.FC<CommentsBlockProps> = ({ dashboardType }) =
                                 icon={<FontAwesomeIcon icon={faFileChartPie} />}
                                 variant="primary"
                                 size="small"
-                                onClick={handleViewDashboard}
+                                href={dashboardURL}
                             >
                                 {translate('commentDashboard.block.buttonText')}
                             </Button>

web/src/components/engagement/preview/EngagementPreview.tsx

@@ -1,5 +1,5 @@
 import React, { useEffect, useState, useRef, useMemo } from 'react';
-import { useBlocker, useLoaderData, useParams, useRevalidator } from 'react-router';
+import { useBlocker, useRouteLoaderData, useParams, useRevalidator } from 'react-router';
 import { Box, Modal } from '@mui/material';
 import PreviewControlBar from './PreviewControlBar';
 import PreviewContent from './PreviewContent';
@@ -186,7 +186,7 @@ const MeasurementBar: React.FC = () => {
  * modifying the actual engagement.
  */
 export const EngagementPreview: React.FC = () => {
-    const loaderData = useLoaderData() as EngagementLoaderPublicData;
+    const loaderData = useRouteLoaderData('public-single-engagement') as EngagementLoaderPublicData;
     const { engagementId, languageCode } = useParams();
     const revalidator = useRevalidator();
     const [previewState, setPreviewState] = useState<SubmissionStatusTypes>('Upcoming');

web/src/components/engagement/preview/PreviewLoaderDataContext.tsx

@@ -1,5 +1,5 @@
 import React, { createContext, useContext } from 'react';
-import { useLoaderData } from 'react-router';
+import { useRouteLoaderData } from 'react-router';
 import { EngagementLoaderPublicData } from 'components/engagement/public/view/EngagementLoaderPublic';
 
 const PreviewLoaderDataContext = createContext<EngagementLoaderPublicData | null>(null);
@@ -15,7 +15,7 @@ export const PreviewLoaderDataProvider: React.FC<PreviewLoaderDataProviderProps>
 
 export const useEngagementLoaderData = (): EngagementLoaderPublicData => {
     const previewLoaderData = useContext(PreviewLoaderDataContext);
-    const routeLoaderData = useLoaderData() as EngagementLoaderPublicData;
+    const routeLoaderData = useRouteLoaderData('public-single-engagement') as EngagementLoaderPublicData;
     return previewLoaderData ?? routeLoaderData;
 };
 

web/src/components/engagement/public/view/EngagementLoaderPublic.tsx

@@ -24,6 +24,18 @@ export type EngagementLoaderPublicData = {
     translationBundle: Promise<TranslationBundle>;
 };
 
+export type AwaitedEngagementLoaderPublicData = {
+    engagement: Engagement;
+    widgets: Widget[];
+    details: EngagementDetailsTab[];
+    metadata: EngagementMetadata[];
+    taxa: MetadataTaxon[];
+    languages: Language[];
+    translationLanguages?: Language[];
+    suggestions: SuggestedEngagementWithAttachment[];
+    translationBundle: TranslationBundle;
+};
+
 export const engagementLoaderPublic = async ({ params }: { params: Params<string> }) => {
     const { slug: slugParam, engagementId, language } = params;
     const defaultLanguageCode = AppConfig.language.defaultLanguageId.toLowerCase();

web/src/components/engagement/public/view/SuggestedEngagements.tsx

@@ -6,7 +6,7 @@ import { Heading2 } from 'components/common/Typography';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 import { faArrowLeftLong } from '@fortawesome/pro-regular-svg-icons';
 import { Link } from 'components/common/Navigation';
-import { Await, useLoaderData } from 'react-router';
+import { Await, useRouteLoaderData } from 'react-router';
 
 import { EngagementLoaderPublicData } from './EngagementLoaderPublic';
 import { EngagementViewSections } from '.';
@@ -19,7 +19,9 @@ import { getPath, ROUTES } from 'routes/routes';
 import { TranslationBundle, resolveTranslationValue } from './engagementTranslationResolution';
 
 export const SuggestedEngagements = () => {
-    const { suggestions, engagement, translationBundle } = useLoaderData() as EngagementLoaderPublicData;
+    const { suggestions, engagement, translationBundle } = useRouteLoaderData(
+        'public-single-engagement',
+    ) as EngagementLoaderPublicData;
     const engagementSlots = Array.from({ length: 3 });
     const { isPreviewMode } = usePreview();