@firecms/core 3.5.2-canary.09e1281 → 3.5.2-canary.c5764a3

package/dist/internal/useUnsavedChangesDialog.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Custom hook to handle navigation blocking when there are unsaved changes.
+ *
+ * @param when - Indicates whether to block navigation.
+ * @param onSuccess - Callback invoked when navigation is confirmed.
+ * @returns An object containing the state of navigation blocking and handlers.
+ */
+export declare function useNavigationUnsavedChangesDialog(when: boolean, onSuccess: () => void): {
+    navigationWasBlocked: boolean;
+    handleCancel: () => void;
+    handleOk: () => void;
+};

package/dist/types/side_dialogs_controller.d.ts

@@ -5,11 +5,9 @@ import React from "react";
  */
 export interface SideDialogsController {
     /**
-     * Close the last panel.
-     * When the `key` of a panel without a URL is given, that panel is closed
-     * instead, even if other panels are open on top of it.
+     * Close the last panel
      */
-    close: (key?: string) => void;
+    close: () => void;
     /**
      * List of side panels currently open
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@firecms/core",
   "type": "module",
-  "version": "3.5.2-canary.09e1281",
+  "version": "3.5.2-canary.c5764a3",
   "description": "Awesome Firebase/Firestore-based headless open-source CMS",
   "funding": {
     "url": "https://github.com/sponsors/firecmsco"
@@ -53,8 +53,8 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
-    "@firecms/formex": "3.5.2-canary.09e1281",
-    "@firecms/ui": "3.5.2-canary.09e1281",
+    "@firecms/formex": "3.5.2-canary.c5764a3",
+    "@firecms/ui": "3.5.2-canary.c5764a3",
     "@floating-ui/dom": "^1.7.4",
     "@radix-ui/react-portal": "^1.1.10",
     "@radix-ui/react-slot": "^1.2.4",

package/src/components/EntityCollectionView/EntityCollectionView.tsx

@@ -8,6 +8,7 @@ import {
     Entity,
     EntityAction,
     EntityCollection,
+    EntityReference,
     EntityTableController,
     FilterValues,
     PartialEntityCollection,
@@ -58,9 +59,14 @@ import {
     AddIcon,
     Button,
     cls,
+    focusedDisabled,
+    IconButton,
     KeyboardTabIcon,
     Markdown,
+    Popover,
+    SearchIcon,
     Skeleton,
+    Tooltip,
     Typography
 } from "@firecms/ui";
 import { setIn } from "@firecms/formex";
@@ -82,8 +88,7 @@ import { DeleteEntityDialog } from "../DeleteEntityDialog";
 import { useAnalyticsController } from "../../hooks/useAnalyticsController";
 import { useSelectionController } from "./useSelectionController";
 import { EntityCollectionViewStartActions } from "./EntityCollectionViewStartActions";
-import { addRecentId } from "./utils";
-import { EntityIdHeaderWidget } from "./EntityIdHeaderWidget";
+import { addRecentId, getRecentIds } from "./utils";
 import { useScrollRestoration } from "../common/useScrollRestoration";
 import { entityCacheKey } from "../../util/entity_cache";
 
@@ -126,12 +131,6 @@ export type EntityCollectionViewProps<M extends Record<string, any>> = {
      */
     updateUrl?: boolean;
 
-    /**
-     * Called with the number of entities in the collection, with the current filters
-     * applied, each time it is counted: the count the breadcrumbs show.
-     */
-    onCountChange?: (count: number) => void;
-
 } & EntityCollection<M>;
 
 /**
@@ -167,7 +166,6 @@ export const EntityCollectionView = React.memo(
         isSubCollection,
         className,
         updateUrl,
-        onCountChange,
         ...collectionProp
     }: EntityCollectionViewProps<M>
     ) {
@@ -352,7 +350,7 @@ export const EntityCollectionView = React.memo(
             });
 
             if (collection) {
-                addRecentId(fullIdPath ?? fullPath, clickedEntity.id);
+                addRecentId(collection.id, clickedEntity.id);
             }
 
             // In a collection group the row's own path is the real one, so the row's segments
@@ -797,9 +795,8 @@ export const EntityCollectionView = React.memo(
         useEffect(() => {
             if (docsCount !== undefined) {
                 breadcrumbs.updateCount(fullPath, docsCount);
-                onCountChange?.(docsCount);
             }
-        }, [docsCount, fullPath, breadcrumbs.updateCount, onCountChange]);
+        }, [docsCount, fullPath, breadcrumbs.updateCount]);
 
         // EntitiesCount fetches count and updates breadcrumb - no visual rendering needed here
         const countFetcher = <EntitiesCount
@@ -1201,3 +1198,105 @@ function buildPropertyWidthOverwrite(key: string, width: number): PartialEntityC
     }
     return { properties: { [key]: { columnWidth: width } } } as PartialEntityCollection;
 }
+
+function EntityIdHeaderWidget({
+    collection,
+    path,
+    pathSegments,
+    fullIdPath
+}: {
+    collection: EntityCollection,
+    path: string,
+    /** `path` split at its real segment boundaries, when the caller knows them. */
+    pathSegments?: string[],
+    fullIdPath: string
+}) {
+
+    const navigation = useNavigationController();
+    const [openPopup, setOpenPopup] = React.useState(false);
+    const [searchString, setSearchString] = React.useState("");
+    const [recentIds, setRecentIds] = React.useState<string[]>(getRecentIds(collection.id));
+    const sideEntityController = useSideEntityController();
+    const { t } = useTranslation();
+
+    const openEntityMode = collection?.openEntityMode ?? DEFAULT_ENTITY_OPEN_MODE;
+
+    return (
+        <Tooltip title={!openPopup ? t("find_by_id") : undefined} asChild={false}>
+            <Popover
+                open={openPopup}
+                onOpenChange={setOpenPopup}
+                sideOffset={0}
+                align={"start"}
+                alignOffset={-117}
+                trigger={
+                    <IconButton size={"small"}>
+                        <SearchIcon size={"small"} />
+                    </IconButton>
+                }>
+                <div
+                    className={cls("my-2 rounded-lg bg-surface-50 dark:bg-surface-950 text-surface-900 dark:text-white")}>
+                    <form noValidate={true}
+                        onSubmit={(e) => {
+                            e.preventDefault();
+                            if (!searchString) return;
+                            setOpenPopup(false);
+                            const entityId = searchString.trim();
+                            setRecentIds(addRecentId(collection.id, entityId));
+                            navigateToEntity({
+                                openEntityMode,
+                                collection,
+                                entityId,
+                                path,
+                                pathSegments,
+                                fullIdPath,
+                                sideEntityController,
+                                navigation
+                            })
+                        }}
+                        className={"w-96 max-w-full"}>
+
+                        <div className="flex p-2 w-full gap-2">
+                            <input
+                                autoFocus={openPopup}
+                                placeholder={t("find_entity_by_id")}
+                                // size={"small"}
+                                onChange={(e) => {
+                                    setSearchString(e.target.value);
+                                }}
+                                value={searchString}
+                                className={"rounded-lg bg-white dark:bg-surface-800 flex-grow bg-transparent outline-none p-2 " + focusedDisabled} />
+                            <Button variant={"text"}
+                                disabled={!(searchString.trim())}
+                                type={"submit"}
+                            ><KeyboardTabIcon /></Button>
+                        </div>
+                    </form>
+                    {recentIds && recentIds.length > 0 && <div className="flex flex-col gap-2 p-2">
+                        {recentIds.map(id => (
+                            <ReferencePreview reference={new EntityReference(id, path, undefined, pathSegments)}
+                                key={id}
+                                hover={true}
+                                onClick={() => {
+                                    setOpenPopup(false);
+                                    navigateToEntity({
+                                        openEntityMode,
+                                        collection,
+                                        entityId: id,
+                                        path,
+                                        pathSegments,
+                                        fullIdPath,
+                                        sideEntityController,
+                                        navigation
+                                    })
+                                }}
+                                includeEntityLink={false}
+                                size={"small"} />
+                        ))}
+                    </div>}
+                </div>
+            </Popover>
+
+        </Tooltip>
+    );
+}

package/src/components/EntityCollectionView/utils.ts

@@ -1,19 +1,19 @@
 import { getLocalStorageJSON, setLocalStorageItem } from "../../util/local_storage";
 
-export function addRecentId(key: string, id: string) {
-    const recentIds = getRecentIds(key);
+export function addRecentId(collectionId: string, id: string) {
+    const recentIds = getRecentIds(collectionId);
     const newRecentIds = [id, ...recentIds.filter(i => i !== id)];
     if (newRecentIds.length > 5) {
         newRecentIds.pop();
     }
-    saveSearchedIdsLocally(key, newRecentIds);
+    saveSearchedIdsLocally(collectionId, newRecentIds);
     return newRecentIds;
 }
 
-export function saveSearchedIdsLocally(key: string, ids: string[]) {
-    setLocalStorageItem("recent_id_searches::" + key, JSON.stringify(ids));
+export function saveSearchedIdsLocally(collectionId: string, ids: string[]) {
+    setLocalStorageItem("recent_id_searches::" + collectionId, JSON.stringify(ids));
 }
 
-export function getRecentIds(key: string): string[] {
-    return getLocalStorageJSON("recent_id_searches::" + key, []);
+export function getRecentIds(collectionId: string): string[] {
+    return getLocalStorageJSON("recent_id_searches::" + collectionId, []);
 }

package/src/components/common/default_entity_actions.tsx

@@ -38,8 +38,7 @@ export const editEntityAction: EntityAction = {
         });
 
         if (collection) {
-            // the same key the collection view's "find by id" reads them with
-            addRecentId(fullIdPath ?? fullPath ?? collection.id, entity.id);
+            addRecentId(collection.id, entity.id);
         }
 
         const path = collection?.collectionGroup ? entity.path : (fullPath ?? collection?.path ?? entity.path);

package/src/core/DefaultAppBar.tsx

@@ -21,8 +21,6 @@ import { User } from "../types";
 import { useApp } from "../app/useApp";
 import { useBreadcrumbsController } from "../hooks/useBreadcrumbsController";
 import { DrawerLogo } from "./DefaultDrawer";
-import { CollectionCountBadge } from "../components/EntityCollectionView/CollectionCountBadge";
-import { PathTitle } from "../components/EntityCollectionView/CollectionPathTitle";
 
 export type DefaultAppBarProps<ADDITIONAL_PROPS = object> = {
 
@@ -83,7 +81,6 @@ export const DefaultAppBar = function DefaultAppBar({
     const navigation = useNavigationController();
 
     const breadcrumbs = useBreadcrumbsController();
-    const lastBreadcrumb = breadcrumbs.breadcrumbs?.[breadcrumbs.breadcrumbs.length - 1];
 
     const authController = useAuthController();
     const {
@@ -180,7 +177,15 @@ export const DefaultAppBar = function DefaultAppBar({
                                         {breadcrumb.title}
                                     </Typography>
                                     {/* Show count badge for collection breadcrumbs: undefined = not applicable, null = loading, number = count */}
-                                    <CollectionCountBadge count={breadcrumb.count}/>
+                                    {breadcrumb.count !== undefined && (
+                                        breadcrumb.count !== null ? (
+                                            <span className="text-xs text-surface-accent-500 dark:text-surface-accent-400 bg-surface-100 dark:bg-surface-700 px-1 py-0 rounded">
+                                                {breadcrumb.count}
+                                            </span>
+                                        ) : (
+                                            <Skeleton className="w-8 h-4 rounded-md" />
+                                        )
+                                    )}
                                 </div>
                             </Link>
                         </React.Fragment>;
@@ -188,14 +193,6 @@ export const DefaultAppBar = function DefaultAppBar({
                 </div>
             </div>}
 
-            {/* A row of breadcrumbs does not fit a small screen, but where you are and how
-                many entities are there still matter, so they are folded on two lines. */}
-            {lastBreadcrumb && <PathTitle
-                className={"lg:hidden min-w-0 mr-2"}
-                parents={breadcrumbs.breadcrumbs.slice(0, -1).map(breadcrumb => breadcrumb.title)}
-                name={lastBreadcrumb.title}
-                count={lastBreadcrumb.count}/>}
-
 
             {startAdornment}
 

package/src/core/EntityEditView.tsx

@@ -24,7 +24,6 @@ import {
 import {
     useAuthController,
     useCustomizationController,
-    useDataSource,
     useEntityFetch,
     useFireCMSContext,
     useLargeLayout
@@ -36,7 +35,6 @@ import { EntityEditViewFormActions } from "./EntityEditViewFormActions";
 import { EntityJsonPreview } from "../components/EntityJsonPreview";
 import { createFormexStub } from "../util/createFormexStub";
 import { useTranslation } from "../hooks/useTranslation";
-import { CollectionPathTitle } from "../components/EntityCollectionView/CollectionPathTitle";
 
 export const MAIN_TAB_VALUE = "__main_##Q$SC^#S6";
 export const JSON_TAB_VALUE = "__json";
@@ -240,11 +238,6 @@ export function EntityEditViewInner<M extends Record<string, any>>({
 
     const subcollections = (collection.subcollections ?? []).filter(c => !c.hideFromNavigation);
     const subcollectionsCount = subcollections?.length ?? 0;
-
-    // The number of entities in each subcollection tab, as its collection view counts them.
-    const [subcollectionCounts, setSubcollectionCounts] = useState<Record<string, number>>({});
-    const selectedSubcollection = subcollections.find(subcollection => (subcollection.id ?? subcollection.path) === selectedTab);
-    const selectedSubcollectionDataSource = useDataSource(selectedSubcollection ?? collection);
     const customViews = collection.entityViews ?? [];
     const customViewsCount = customViews?.length ?? 0;
     const includeJsonView = collection.includeJsonView === undefined ? true : collection.includeJsonView;
@@ -393,9 +386,7 @@ export function EntityEditViewInner<M extends Record<string, any>>({
                             isSubCollection={true}
                             updateUrl={false}
                             {...subcollection}
-                            openEntityMode={layout}
-                            onCountChange={(count) => setSubcollectionCounts(counts =>
-                                counts[subcollectionId] === count ? counts : { ...counts, [subcollectionId]: count })} />
+                            openEntityMode={layout} />
                         : <div className="flex items-center justify-center w-full h-full p-3">
                             <Typography variant={"label"}>
                                 {t("youd_need_to_save_before_additional_collections")}
@@ -543,20 +534,6 @@ export function EntityEditViewInner<M extends Record<string, any>>({
 
     const shouldShowTopBar = Boolean(barActions) || hasAdditionalViews;
 
-    // A side panel covers the app bar's breadcrumbs, which show where a collection is and
-    // how many entities it has, so the panel shows its subcollection's in its own top bar.
-    const subcollectionTitle = layout === "side_panel" && selectedSubcollection && usedEntity
-        ? (() => {
-            const subcollectionId = selectedSubcollection.id ?? selectedSubcollection.path;
-            return <CollectionPathTitle
-                path={fullIdPath
-                    ? `${fullIdPath}/${encodeEntityId(usedEntity.id)}/${removeInitialAndTrailingSlashes(subcollectionId)}`
-                    : `${path}/${usedEntity.id}/${removeInitialAndTrailingSlashes(selectedSubcollection.path)}`}
-                name={selectedSubcollection.name}
-                count={subcollectionCounts[subcollectionId] ?? (selectedSubcollectionDataSource.countEntities ? null : undefined)}/>;
-        })()
-        : null;
-
     let result = <div className="relative flex flex-col h-full w-full bg-white dark:bg-surface-900">
 
         {shouldShowTopBar && <div
@@ -569,8 +546,6 @@ export function EntityEditViewInner<M extends Record<string, any>>({
                 status
             })}
 
-            {subcollectionTitle}
-
             <div className={"flex-grow"} />
 
             {pluginActionsTop}

package/src/core/SideDialogs.tsx

@@ -2,7 +2,7 @@ import React, { useContext, useEffect, useRef, useState } from "react";
 import { useSideDialogsController } from "../hooks";
 import { EntitySidePanelProps, SideDialogPanelProps } from "../types";
 import { Sheet } from "@firecms/ui";
-import { useLeavePageConfirmation } from "../internal/useLeavePageConfirmation";
+import { useNavigationUnsavedChangesDialog } from "../internal/useUnsavedChangesDialog";
 import { ErrorBoundary } from "../components";
 import { UnsavedChangesDialog } from "../components/UnsavedChangesDialog";
 import { EntitySidePanel } from "./EntitySidePanel";
@@ -123,7 +123,14 @@ function SideDialogView({
 
     const sideDialogsController = useSideDialogsController();
 
-    useLeavePageConfirmation(blocked && !drawerCloseRequested);
+    const {
+        navigationWasBlocked,
+        handleOk: handleNavigationOk,
+        handleCancel: handleNavigationCancel
+    } = useNavigationUnsavedChangesDialog(
+        blocked && !drawerCloseRequested,
+        () => setBlocked(false)
+    );
 
     useEffect(() => {
         if (panel)
@@ -133,7 +140,7 @@ function SideDialogView({
     const handleDrawerCloseOk = () => {
         setBlocked(false);
         setDrawerCloseRequested(false);
-        sideDialogsController.close(panel?.key);
+        sideDialogsController.close();
         panel?.onClose?.();
     };
 
@@ -145,7 +152,7 @@ function SideDialogView({
         if (blocked && !force) {
             setDrawerCloseRequested(true);
         } else {
-            sideDialogsController.close(panel?.key);
+            sideDialogsController.close();
             panel?.onClose?.();
         }
     };
@@ -205,8 +212,8 @@ function SideDialogView({
 
             <UnsavedChangesDialog
                 open={drawerCloseRequested}
-                handleOk={handleDrawerCloseOk}
-                handleCancel={handleDrawerCloseCancel}
+                handleOk={drawerCloseRequested ? handleDrawerCloseOk : handleNavigationOk}
+                handleCancel={drawerCloseRequested ? handleDrawerCloseCancel : handleNavigationCancel}
                 body={blockedNavigationMessage} />
 
         </SideDialogContext.Provider>

package/src/hooks/useReferenceDialog.tsx

@@ -45,8 +45,8 @@ export function useReferenceDialog<M extends Record<string, any>>(referenceDialo
     }, [navigation, referenceDialogProps, sideDialogsController]);
 
     const close = useCallback(() => {
-        sideDialogsController.close(`reference_${referenceDialogProps.path}`);
-    }, [sideDialogsController, referenceDialogProps.path]);
+        sideDialogsController.close();
+    }, [sideDialogsController]);
 
     return {
         open,

package/src/internal/useBuildSideDialogsController.tsx

@@ -14,9 +14,6 @@ export function useBuildSideDialogsController(): SideDialogsController {
     const routesStore = useRef<Record<string, SideDialogPanelProps>>({});
     const routesCount = useRef<number>(0);
 
-    // The history entry each panel without a URL was opened on, by panel key.
-    const entryKeysOfPanelsWithoutUrl = useRef<Record<string, string>>({});
-
     const updateSidePanels = (newPanels: SideDialogPanelProps[]) => {
         sidePanelsRef.current = newPanels;
         setSidePanels(newPanels);
@@ -25,55 +22,20 @@ export function useBuildSideDialogsController(): SideDialogsController {
     useEffect(() => {
         const state = location.state as any;
         const panelKeys: string[] = state?.panels ?? [];
-        const panelsInHistory = panelKeys
+        const newPanels = panelKeys
             .map(key => routesStore.current[key])
             .filter(p => Boolean(p)) as SideDialogPanelProps[];
-
-        // A panel without a URL, like a reference dialog, pushes no history entry, so the
-        // entry under it does not list it, and going back to that entry, as closing a
-        // panel opened on top of it does, would drop it. It stays open for as long as
-        // what it was opened over does: the panel below it or, with none, the entry itself.
-        const keptPanels: SideDialogPanelProps[] = [];
-        let matched = 0;
-        for (const panel of sidePanelsRef.current) {
-            if (panelsInHistory[matched]?.key === panel.key) {
-                keptPanels.push(panel);
-                matched++;
-            } else if (!panel.urlPath &&
-                (keptPanels.length > 0 || entryKeysOfPanelsWithoutUrl.current[panel.key] === location.key)) {
-                keptPanels.push(panel);
-            } else {
-                break;
-            }
-        }
-        const newPanels = [...keptPanels, ...panelsInHistory.slice(matched)];
-
         if (!equal(sidePanelsRef.current.map(p => p.key), newPanels.map(p => p.key))) {
             updateSidePanels(newPanels);
         }
     }, [location]);
 
-    const close = useCallback((key?: string) => {
+    const close = useCallback(() => {
 
         const currentPanels = sidePanelsRef.current;
         if (currentPanels.length === 0)
             return;
 
-        // A panel can ask to close itself while another one is open on top of it: the
-        // reference dialog does when an entity created from it is saved. Closing the top
-        // one instead would close that entity, and then the entity's own close would take
-        // the panel under the dialog with it. Only a panel without a URL can be taken out
-        // of the middle, since it has no history entry of its own. Should two panels share
-        // a key (a reference dialog opened from an entity created in another one for the
-        // same collection), it is the upper one.
-        const index = key !== undefined ? currentPanels.findLastIndex(p => p.key === key) : -1;
-        if (index !== -1 && index < currentPanels.length - 1 && !currentPanels[index].urlPath) {
-            updateSidePanels(currentPanels.filter((_, i) => i !== index));
-            if (routesCount.current > 0)
-                routesCount.current--;
-            return;
-        }
-
         const lastSidePanel = currentPanels[currentPanels.length - 1];
         const updatedPanels = [...currentPanels.slice(0, -1)];
         updateSidePanels(updatedPanels);
@@ -103,8 +65,6 @@ export function useBuildSideDialogsController(): SideDialogsController {
 
         newPanels.forEach((panel) => {
             routesStore.current[panel.key] = panel;
-            if (!panel.urlPath)
-                entryKeysOfPanelsWithoutUrl.current[panel.key] = location.key;
         });
         routesCount.current = routesCount.current + newPanels.length;
 
@@ -135,8 +95,6 @@ export function useBuildSideDialogsController(): SideDialogsController {
         const newPanels: SideDialogPanelProps[] = Array.isArray(panelProps) ? panelProps : [panelProps];
         newPanels.forEach((panel) => {
             routesStore.current[panel.key] = panel;
-            if (!panel.urlPath)
-                entryKeysOfPanelsWithoutUrl.current[panel.key] = location.key;
         });
 
         const baseLocation = (location.state as any)?.base_location ?? location;

package/src/internal/useUnsavedChangesDialog.tsx

@@ -0,0 +1,142 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { Button, Dialog, DialogActions, DialogContent, DialogTitle, Typography } from "@firecms/ui";
+
+/**
+ * Type representing a pending navigation action.
+ */
+type PendingNavigation =
+    | {
+    type: "popstate";
+    delta: number;
+}
+    | {
+    type: "link";
+    href: string;
+}
+    | null;
+
+/**
+ * Custom hook to handle navigation blocking when there are unsaved changes.
+ *
+ * @param when - Indicates whether to block navigation.
+ * @param onSuccess - Callback invoked when navigation is confirmed.
+ * @returns An object containing the state of navigation blocking and handlers.
+ */
+export function useNavigationUnsavedChangesDialog(
+    when: boolean,
+    onSuccess: () => void
+): {
+    navigationWasBlocked: boolean;
+    handleCancel: () => void;
+    handleOk: () => void;
+} {
+    const [isDialogOpen, setIsDialogOpen] = useState<boolean>(false);
+    const [pendingNavigation, setPendingNavigation] = useState<PendingNavigation>(null);
+
+    /**
+     * Handler to cancel the navigation attempt.
+     */
+    const handleCancel = useCallback(() => {
+        setIsDialogOpen(false);
+        setPendingNavigation(null);
+    }, []);
+
+    /**
+     * Handler to confirm and proceed with the navigation.
+     */
+    const handleOk = useCallback(() => {
+        setIsDialogOpen(false);
+        if (pendingNavigation) {
+            onSuccess();
+            if (pendingNavigation.type === "popstate") {
+                window.history.go(pendingNavigation.delta);
+            } else if (pendingNavigation.type === "link") {
+                window.location.href = pendingNavigation.href;
+            }
+            setPendingNavigation(null);
+        }
+    }, [onSuccess, pendingNavigation]);
+
+    /**
+     * Event handler for beforeunload to handle page refresh or tab close.
+     */
+    const handleBeforeUnload = useCallback(
+        (e: BeforeUnloadEvent) => {
+            if (when) {
+                e.preventDefault();
+                e.returnValue = "";
+            }
+        },
+        [when]
+    );
+
+    /**
+     * Event handler for popstate to handle back and forward browser buttons.
+     */
+    const handlePopState = useCallback(
+        (e: PopStateEvent) => {
+            if (when) {
+                e.preventDefault();
+                // Assuming backward navigation; adjust delta as needed
+                setPendingNavigation({
+                    type: "popstate",
+                    delta: -1
+                });
+                setIsDialogOpen(true);
+            }
+        },
+        [when]
+    );
+
+    /**
+     * Event handler to intercept link clicks within the application.
+     */
+    const handleLinkClick = useCallback(
+        (e: MouseEvent) => {
+            if (!when) return;
+
+            const target = e.target as HTMLElement;
+            const anchor = target.closest("a[href]") as HTMLAnchorElement | null;
+            if (anchor && anchor.host === window.location.host) {
+                e.preventDefault();
+                const href = anchor.getAttribute("href");
+                if (href) {
+                    setPendingNavigation({
+                        type: "link",
+                        href
+                    });
+                    setIsDialogOpen(true);
+                }
+            }
+        },
+        [when]
+    );
+
+    /**
+     * Effect hook to add and clean up event listeners based on the `when` condition.
+     */
+    useEffect(() => {
+        if (when) {
+            window.addEventListener("beforeunload", handleBeforeUnload);
+            window.addEventListener("popstate", handlePopState);
+            document.addEventListener("click", handleLinkClick);
+        } else {
+            window.removeEventListener("beforeunload", handleBeforeUnload);
+            window.removeEventListener("popstate", handlePopState);
+            document.removeEventListener("click", handleLinkClick);
+        }
+
+        // Cleanup on unmount or when `when` changes
+        return () => {
+            window.removeEventListener("beforeunload", handleBeforeUnload);
+            window.removeEventListener("popstate", handlePopState);
+            document.removeEventListener("click", handleLinkClick);
+        };
+    }, [when, handleBeforeUnload, handlePopState, handleLinkClick]);
+
+    return {
+        navigationWasBlocked: isDialogOpen,
+        handleCancel,
+        handleOk,
+    };
+}