dce-reactkit 5.0.8 → 5.0.10

package/dist/cjs/types/helpers/useBackButton.d.ts

@@ -0,0 +1,20 @@
+import BackButtonController from '../types/BackButtonController';
+/**
+ * Controller for driving back navigation from anywhere in the app. Requires
+ *   useBackButton to have been called in the top-level app
+ * @author Yuen Ler Chow
+ */
+export declare const backButtonController: BackButtonController;
+/**
+ * Hook that makes the browser's back button navigate within the app instead of
+ *   leaving it. Call this once in your top-level app, then use
+ *   backButtonController to enter subpanels and describe their state.
+ *
+ * Assumes a single level of navigation: one home screen plus subpanels that the
+ *   user returns home from.
+ * @author Yuen Ler Chow
+ * @param handleGoHomeFunc handler that performs the app state changes required
+ *   to return to the home screen
+ */
+declare const useBackButton: (handleGoHomeFunc: () => void) => void;
+export default useBackButton;

package/dist/cjs/types/index.d.ts

@@ -1,4 +1,4 @@
-import { ErrorWithCode, MINUTE_IN_MS, HOUR_IN_MS, DAY_IN_MS, LOG_REVIEW_ROUTE_PATH_PREFIX, LOG_ROUTE_PATH, LOG_REVIEW_STATUS_ROUTE, LOG_REVIEW_GET_LOGS_ROUTE, SELECT_ADMIN_CHECK_ROUTE, abbreviate, avg, ceilToNumDecimals, floorToNumDecimals, forceNumIntoBounds, padDecimalZeros, padZerosLeft, roundToNumDecimals, sum, waitMs, getOrdinal, getTimeInfoInET, getMondayOfTimestamp, startMinWait, getHumanReadableDate, getPartOfDay, stringsToHumanReadableList, onlyKeepLetters, parallelLimit, getMonthName, genCSV, extractProp, compareArraysByProp, getLocalTimeInfo, genCommaList, validateEmail, validatePhoneNumber, validateString, idify, prefixWithAOrAn, everyAsync, filterAsync, forEachAsync, mapAsync, someAsync, capitalize, shuffleArray, getWordCount, cloneDeep, getTimestampFromTimeInfoInET, spaceAtCapitals, ParamType, DayOfWeek, Log, LogType, LogSource, LogAction, LogBuiltInMetadata, LogMetadataType, LogFunction, LogTypeSpecificInfo, LogMainInfo, LogSourceSpecificInfo, LogLevel, CommonKitErrorCode, LogReviewerFilterState } from 'dce-commonkit';
+import { ErrorWithCode, MINUTE_IN_MS, HOUR_IN_MS, DAY_IN_MS, LOG_REVIEW_ROUTE_PATH_PREFIX, LOG_ROUTE_PATH, LOG_REVIEW_STATUS_ROUTE, LOG_REVIEW_GET_LOGS_ROUTE, SELECT_ADMIN_CHECK_ROUTE, abbreviate, avg, ceilToNumDecimals, convertDateKeyToDateInfo, floorToNumDecimals, forceNumIntoBounds, padDecimalZeros, padZerosLeft, roundToNumDecimals, sum, waitMs, getOrdinal, getTimeInfoInET, getMondayOfTimestamp, startMinWait, getHumanReadableDate, getPartOfDay, stringsToHumanReadableList, onlyKeepLetters, parallelLimit, getMonthName, genCSV, extractProp, compareArraysByProp, getLocalTimeInfo, genCommaList, validateEmail, validatePhoneNumber, validateString, idify, prefixWithAOrAn, everyAsync, filterAsync, forEachAsync, mapAsync, someAsync, capitalize, shuffleArray, getWordCount, cloneDeep, getTimestampFromTimeInfoInET, spaceAtCapitals, ParamType, DayOfWeek, Log, LogType, LogSource, LogAction, LogBuiltInMetadata, LogMetadataType, LogFunction, LogTypeSpecificInfo, LogMainInfo, LogSourceSpecificInfo, LogLevel, CommonKitErrorCode, LogReviewerFilterState } from 'dce-commonkit';
 import AppWrapper, { alert, prompt, confirm, showFatalError, addFatalErrorHandler, leaveToURL } from './components/AppWrapper';
 import LoadingSpinner from './components/LoadingSpinner';
 import ErrorBox from './components/ErrorBox';
@@ -37,6 +37,7 @@ import isMobileOrTablet from './helpers/isMobileOrTablet';
 import makeLinksClickable from './helpers/makeLinksClickable';
 import combineClassNames from './helpers/combineClassNames';
 import useForceRender from './helpers/useForceRender';
+import useBackButton, { backButtonController } from './helpers/useBackButton';
 import isSelectAdmin from './helpers/isSelectAdmin';
 import ModalButtonType from './types/ModalButtonType';
 import ModalSize from './types/ModalSize';
@@ -45,8 +46,10 @@ import Variant from './types/Variant';
 import IntelliTableColumn from './types/IntelliTableColumn';
 import DropdownItemType from './types/DropdownItemType';
 import ProgressBarSize from './types/ProgressBarSize';
+import BackState from './types/BackState';
+import BackButtonController from './types/BackButtonController';
 import PickableItem from './components/ItemPicker/types/PickableItem';
 import DBEntry from './components/DBEntryManagerPanel/types/DBEntry';
 import DBEntryField from './components/DBEntryManagerPanel/types/DBEntryField';
 import DBEntryFieldType from './components/DBEntryManagerPanel/types/DBEntryFieldType';
-export { AppWrapper, LoadingSpinner, ErrorBox, Modal, TabBox, RadioButton, CheckboxButton, ButtonInputGroup, SimpleDateChooser, SimpleMonthChooser, SimpleTimeChooser, Drawer, PopSuccessMark, PopFailureMark, PopPendingMark, CopiableBox, ItemPicker, LogReviewer, IntelliTable, CSVDownloadButton, DBEntryManagerPanel, Tooltip, ToggleSwitch, AutoscrollToBottomContainer, MultiSwitch, Dropdown, ProgressBar, FakeProgressBar, alert, prompt, confirm, showFatalError, DynamicWord, stubServerEndpoint, canReviewLogs, isMobileOrTablet, makeLinksClickable, isSelectAdmin, initClient, visitServerEndpoint, logClientEvent, addFatalErrorHandler, leaveToURL, combineClassNames, useForceRender, setClientEventMetadataPopulator, ModalButtonType, ModalSize, ModalType, Variant, IntelliTableColumn, DropdownItemType, LogReviewerFilterState, ProgressBarSize, PickableItem, DBEntry, DBEntryField, DBEntryFieldType, ErrorWithCode, MINUTE_IN_MS, HOUR_IN_MS, DAY_IN_MS, LOG_REVIEW_ROUTE_PATH_PREFIX, LOG_ROUTE_PATH, LOG_REVIEW_STATUS_ROUTE, LOG_REVIEW_GET_LOGS_ROUTE, SELECT_ADMIN_CHECK_ROUTE, abbreviate, avg, ceilToNumDecimals, floorToNumDecimals, forceNumIntoBounds, padDecimalZeros, padZerosLeft, roundToNumDecimals, sum, waitMs, getOrdinal, getTimeInfoInET, getMondayOfTimestamp, startMinWait, getHumanReadableDate, getPartOfDay, stringsToHumanReadableList, onlyKeepLetters, parallelLimit, getMonthName, genCSV, extractProp, compareArraysByProp, getLocalTimeInfo, genCommaList, validateEmail, validatePhoneNumber, validateString, idify, prefixWithAOrAn, everyAsync, filterAsync, forEachAsync, mapAsync, someAsync, capitalize, shuffleArray, getWordCount, cloneDeep, getTimestampFromTimeInfoInET, spaceAtCapitals, ParamType, DayOfWeek, Log, LogType, LogSource, LogAction, LogBuiltInMetadata, LogMetadataType, LogFunction, LogTypeSpecificInfo, LogMainInfo, LogSourceSpecificInfo, LogLevel, CommonKitErrorCode, };
+export { AppWrapper, LoadingSpinner, ErrorBox, Modal, TabBox, RadioButton, CheckboxButton, ButtonInputGroup, SimpleDateChooser, SimpleMonthChooser, SimpleTimeChooser, Drawer, PopSuccessMark, PopFailureMark, PopPendingMark, CopiableBox, ItemPicker, LogReviewer, IntelliTable, CSVDownloadButton, DBEntryManagerPanel, Tooltip, ToggleSwitch, AutoscrollToBottomContainer, MultiSwitch, Dropdown, ProgressBar, FakeProgressBar, alert, prompt, confirm, showFatalError, DynamicWord, stubServerEndpoint, canReviewLogs, isMobileOrTablet, makeLinksClickable, isSelectAdmin, initClient, visitServerEndpoint, logClientEvent, addFatalErrorHandler, leaveToURL, combineClassNames, useForceRender, useBackButton, backButtonController, setClientEventMetadataPopulator, ModalButtonType, ModalSize, ModalType, Variant, IntelliTableColumn, DropdownItemType, LogReviewerFilterState, ProgressBarSize, BackState, BackButtonController, PickableItem, DBEntry, DBEntryField, DBEntryFieldType, ErrorWithCode, MINUTE_IN_MS, HOUR_IN_MS, DAY_IN_MS, LOG_REVIEW_ROUTE_PATH_PREFIX, LOG_ROUTE_PATH, LOG_REVIEW_STATUS_ROUTE, LOG_REVIEW_GET_LOGS_ROUTE, SELECT_ADMIN_CHECK_ROUTE, abbreviate, avg, ceilToNumDecimals, convertDateKeyToDateInfo, floorToNumDecimals, forceNumIntoBounds, padDecimalZeros, padZerosLeft, roundToNumDecimals, sum, waitMs, getOrdinal, getTimeInfoInET, getMondayOfTimestamp, startMinWait, getHumanReadableDate, getPartOfDay, stringsToHumanReadableList, onlyKeepLetters, parallelLimit, getMonthName, genCSV, extractProp, compareArraysByProp, getLocalTimeInfo, genCommaList, validateEmail, validatePhoneNumber, validateString, idify, prefixWithAOrAn, everyAsync, filterAsync, forEachAsync, mapAsync, someAsync, capitalize, shuffleArray, getWordCount, cloneDeep, getTimestampFromTimeInfoInET, spaceAtCapitals, ParamType, DayOfWeek, Log, LogType, LogSource, LogAction, LogBuiltInMetadata, LogMetadataType, LogFunction, LogTypeSpecificInfo, LogMainInfo, LogSourceSpecificInfo, LogLevel, CommonKitErrorCode, };

package/dist/cjs/types/types/BackButtonController.d.ts

@@ -0,0 +1,40 @@
+import BackState from './BackState';
+/**
+ * Controller for the back button, used to drive back navigation from anywhere
+ *   in the app. Pass this to subpanels so they can describe their state and
+ *   send the user home.
+ * @author Yuen Ler Chow
+ */
+type BackButtonController = {
+    /**
+     * Call this when the user navigates to a child of the home screen (something
+     *   they can come back from)
+     */
+    onSubpanelEntered: () => void;
+    /**
+     * Send the user back to the home screen
+     * @param [force] if true, go home immediately without checking the subpanel
+     *   state (no confirmation, not blocked). If falsy, nothing happens when
+     *   blocked and confirmation is required when there are unsaved changes
+     */
+    goHome: (force?: boolean) => Promise<void>;
+    /**
+     * Set the state of the current subpanel, which determines what happens when
+     *   the user tries to go back
+     * @param newSubpanelState the new state of the subpanel
+     */
+    setSubpanelState: (newSubpanelState: BackState) => void;
+    /**
+     * Set the confirmation message shown if the user tries to go back while there
+     *   are unsaved changes (cleared upon returning to the home screen)
+     * @param message the message to show
+     */
+    setCustomUnsavedChangesMessage: (message: string) => void;
+    /**
+     * Set the message shown if the user tries to go back while blocked (cleared
+     *   upon returning to the home screen)
+     * @param message the message to show
+     */
+    setCustomBlockedMessage: (message: string) => void;
+};
+export default BackButtonController;

package/dist/cjs/types/types/BackState.d.ts

@@ -0,0 +1,11 @@
+/**
+ * State of the current subpanel, determining what happens when the user tries
+ *   to go back to the home screen
+ * @author Yuen Ler Chow
+ */
+declare enum BackState {
+    Normal = "Normal",
+    UnsavedChanges = "UnsavedChanges",
+    Blocked = "Blocked"
+}
+export default BackState;

package/dist/esm/index.js

@@ -1,5 +1,5 @@
 import { CommonKitErrorCode, waitMs, ErrorWithCode, LOG_ROUTE_PATH, LogBuiltInMetadata, LogLevel, getOrdinal, getMonthName, getTimeInfoInET, padZerosLeft, ParamType, roundToNumDecimals, genCSV, LogAction, cloneDeep, LogType, LogSource, getHumanReadableDate, LOG_REVIEW_GET_LOGS_ROUTE, idify, padDecimalZeros, LOG_REVIEW_STATUS_ROUTE, SELECT_ADMIN_CHECK_ROUTE } from 'dce-commonkit';
-export { CommonKitErrorCode, DAY_IN_MS, DayOfWeek, ErrorWithCode, HOUR_IN_MS, LOG_REVIEW_GET_LOGS_ROUTE, LOG_REVIEW_ROUTE_PATH_PREFIX, LOG_REVIEW_STATUS_ROUTE, LOG_ROUTE_PATH, LogAction, LogBuiltInMetadata, LogLevel, LogSource, LogType, MINUTE_IN_MS, ParamType, SELECT_ADMIN_CHECK_ROUTE, abbreviate, avg, capitalize, ceilToNumDecimals, cloneDeep, compareArraysByProp, everyAsync, extractProp, filterAsync, floorToNumDecimals, forEachAsync, forceNumIntoBounds, genCSV, genCommaList, getHumanReadableDate, getLocalTimeInfo, getMondayOfTimestamp, getMonthName, getOrdinal, getPartOfDay, getTimeInfoInET, getTimestampFromTimeInfoInET, getWordCount, idify, mapAsync, onlyKeepLetters, padDecimalZeros, padZerosLeft, parallelLimit, prefixWithAOrAn, roundToNumDecimals, shuffleArray, someAsync, spaceAtCapitals, startMinWait, stringsToHumanReadableList, sum, validateEmail, validatePhoneNumber, validateString, waitMs } from 'dce-commonkit';
+export { CommonKitErrorCode, DAY_IN_MS, DayOfWeek, ErrorWithCode, HOUR_IN_MS, LOG_REVIEW_GET_LOGS_ROUTE, LOG_REVIEW_ROUTE_PATH_PREFIX, LOG_REVIEW_STATUS_ROUTE, LOG_ROUTE_PATH, LogAction, LogBuiltInMetadata, LogLevel, LogSource, LogType, MINUTE_IN_MS, ParamType, SELECT_ADMIN_CHECK_ROUTE, abbreviate, avg, capitalize, ceilToNumDecimals, cloneDeep, compareArraysByProp, convertDateKeyToDateInfo, everyAsync, extractProp, filterAsync, floorToNumDecimals, forEachAsync, forceNumIntoBounds, genCSV, genCommaList, getHumanReadableDate, getLocalTimeInfo, getMondayOfTimestamp, getMonthName, getOrdinal, getPartOfDay, getTimeInfoInET, getTimestampFromTimeInfoInET, getWordCount, idify, mapAsync, onlyKeepLetters, padDecimalZeros, padZerosLeft, parallelLimit, prefixWithAOrAn, roundToNumDecimals, shuffleArray, someAsync, spaceAtCapitals, startMinWait, stringsToHumanReadableList, sum, validateEmail, validatePhoneNumber, validateString, waitMs } from 'dce-commonkit';
 import * as React from 'react';
 import React__default, { useState, useRef, useEffect, useReducer, forwardRef, useContext, useLayoutEffect, createContext, useMemo, useCallback, Component, Fragment } from 'react';
 import { faExclamationTriangle, faCircle, faHourglassEnd, faDotCircle, faCheckSquare, faHourglass, faClipboard, faChevronDown, faChevronRight, faCloudDownloadAlt, faMinus, faCheckCircle, faXmarkCircle, faSort, faSortDown, faSortUp, faArrowLeft, faArrowRight, faCalendar, faTag, faHammer, faList, faTimes, faSearch, faSave, faTrash, faCog, faPlus } from '@fortawesome/free-solid-svg-icons';
@@ -2860,22 +2860,23 @@ const NestableItemList = (props) => {
                 onChanged(changeChecked(item.id, checked, items));
             }, ariaLabel: `Select ${accessibleName}`, checkedVariant: Variant$1.Light, uncheckedVariant: Variant$1.Light }));
         return (React__default.createElement("div", { key: item.id },
-            React__default.createElement("span", { className: "NestableItemList-dropdown-button-container d-inline-block", style: {
-                    minWidth: '2rem',
-                } }, item.isGroup && (React__default.createElement("button", { className: `NestableItemList-dropdown-button NestableItemList-dropdown-button-${item.id}`, style: {
-                    border: 0,
-                    backgroundColor: 'transparent',
-                }, type: "button", onClick: () => {
-                    dispatch({
-                        type: ActionType$9.ToggleChild,
-                        id: item.id,
-                    });
-                }, "aria-label": `${childExpanded[item.id] ? 'Hide' : 'Show'} items in ${accessibleName}` },
-                React__default.createElement(FontAwesomeIcon, { icon: childExpanded[item.id] ? faChevronDown : faChevronRight })))),
-            item.tooltip
-                ? (React__default.createElement(Tooltip, { text: item.tooltip },
-                    React__default.createElement("span", { className: "d-inline-block" }, checkbox)))
-                : checkbox,
+            React__default.createElement("div", { className: "NestableItemList-item d-flex align-items-center" },
+                React__default.createElement("span", { className: "NestableItemList-dropdown-button-container", style: {
+                        minWidth: '2rem',
+                    } }, item.isGroup && (React__default.createElement("button", { className: `NestableItemList-dropdown-button NestableItemList-dropdown-button-${item.id}`, style: {
+                        border: 0,
+                        backgroundColor: 'transparent',
+                    }, type: "button", onClick: () => {
+                        dispatch({
+                            type: ActionType$9.ToggleChild,
+                            id: item.id,
+                        });
+                    }, "aria-label": `${childExpanded[item.id] ? 'Hide' : 'Show'} items in ${accessibleName}` },
+                    React__default.createElement(FontAwesomeIcon, { icon: childExpanded[item.id] ? faChevronDown : faChevronRight })))),
+                item.tooltip
+                    ? (React__default.createElement(Tooltip, { text: item.tooltip },
+                        React__default.createElement("span", { className: "d-inline-block" }, checkbox)))
+                    : checkbox),
             (item.isGroup && childExpanded[item.id]) && (React__default.createElement("div", { className: "NestableItemList-children-container", style: {
                     paddingLeft: '2.2rem',
                 } },
@@ -14751,6 +14752,286 @@ const useForceRender = (useReducer) => {
     };
 };
 
+/**
+ * State of the current subpanel, determining what happens when the user tries
+ *   to go back to the home screen
+ * @author Yuen Ler Chow
+ */
+var BackState;
+(function (BackState) {
+    // The user can go back immediately, no confirmation required
+    BackState["Normal"] = "Normal";
+    // The user must confirm before going back because progress will be lost
+    BackState["UnsavedChanges"] = "UnsavedChanges";
+    // The user cannot go back right now because work is in progress
+    BackState["Blocked"] = "Blocked";
+})(BackState || (BackState = {}));
+var BackState$1 = BackState;
+
+/*------------------------------------------------------------------------*/
+/* ------------------------------ Constants ----------------------------- */
+/*------------------------------------------------------------------------*/
+// Marker stored on history entries owned by this hook
+const HISTORY_STATE_MARKER = { dceReactKitBackButton: true };
+// Default message shown when the user tries to go back while blocked
+const BLOCKED_TITLE = 'Cannot Go Back';
+const BLOCKED_MESSAGE = 'A task is currently in progress. Please try again once it finishes.';
+// Default message shown when the user tries to go back with unsaved changes
+const UNSAVED_CHANGES_TITLE = 'Abandon Changes?';
+const UNSAVED_CHANGES_MESSAGE = 'Any unsaved changes may be lost.';
+/*------------------------------------------------------------------------*/
+/* --------------------------- Static State ----------------------------- */
+/*------------------------------------------------------------------------*/
+// Current state, stored statically so that any subpanel can drive the back
+// button without prop drilling or context
+let state = {
+    promptVisible: false,
+    bypassNextPop: false,
+};
+/*------------------------------------------------------------------------*/
+/* ------------------------- Helper Functions --------------------------- */
+/*------------------------------------------------------------------------*/
+/**
+ * Get the app's go-home handler, throwing if the hook has not been set up yet
+ * @author Yuen Ler Chow
+ * @returns handler that returns the app to its home screen
+ */
+const getHandleGoHome = () => {
+    if (!state.handleGoHome) {
+        throw new Error('Cannot use the back button: call useBackButton in your top-level app before using backButtonController.');
+    }
+    return state.handleGoHome;
+};
+/**
+ * Return to the home screen: clear the current subpanel and run the app's
+ *   go-home handler
+ * @author Yuen Ler Chow
+ * @param consumeHistoryEntry if true, also step back over the history entry
+ *   that was added when the subpanel was entered
+ */
+const returnHome = (consumeHistoryEntry) => {
+    const handleGoHome = getHandleGoHome();
+    const wasInSubpanel = !!state.subpanel;
+    // Dropping the subpanel clears its back state and custom messages at once
+    state.subpanel = undefined;
+    // Update the app
+    handleGoHome();
+    // Entering a subpanel added a history entry. When the user leaves via an
+    // in-app control, that entry is still on the stack, so we step over it to keep
+    // the browser history in sync with the app. When the browser's back button is
+    // what brought us here, that entry has already been consumed by the browser,
+    // and stepping back again would take the user out of the app entirely
+    if (consumeHistoryEntry && wasInSubpanel) {
+        state.bypassNextPop = true;
+        window.history.back();
+    }
+};
+/**
+ * Keep the user in place after a back navigation that should not be allowed.
+ *   The browser's popstate event is not cancelable, so the only way to stay put
+ *   is to immediately push a new entry to replace the one that was just popped.
+ *   This has to happen synchronously while handling the pop, before awaiting
+ *   anything, otherwise the navigation has already taken effect
+ * @author Yuen Ler Chow
+ */
+const undoPop = () => {
+    window.history.pushState(HISTORY_STATE_MARKER, '');
+};
+/**
+ * Tell the user that they cannot go back right now
+ * @author Yuen Ler Chow
+ */
+const showBlockedMessage = () => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
+    state.promptVisible = true;
+    yield alert(BLOCKED_TITLE, (_b = (_a = state.subpanel) === null || _a === void 0 ? void 0 : _a.customBlockedMessage) !== null && _b !== void 0 ? _b : BLOCKED_MESSAGE);
+    state.promptVisible = false;
+});
+/**
+ * Ask the user whether they want to leave despite having unsaved changes
+ * @author Yuen Ler Chow
+ * @returns true if the user wants to leave
+ */
+const askToAbandonChanges = () => __awaiter(void 0, void 0, void 0, function* () {
+    var _c, _d;
+    state.promptVisible = true;
+    const confirmed = yield confirm(UNSAVED_CHANGES_TITLE, (_d = (_c = state.subpanel) === null || _c === void 0 ? void 0 : _c.customUnsavedChangesMessage) !== null && _d !== void 0 ? _d : UNSAVED_CHANGES_MESSAGE, {
+        confirmButtonText: 'Abandon Changes',
+        cancelButtonText: 'Stay Here',
+    });
+    state.promptVisible = false;
+    return confirmed;
+});
+/**
+ * Handle a back navigation performed by the browser
+ * @author Yuen Ler Chow
+ */
+const handlePopState = () => {
+    // Back navigation that we triggered ourselves: let it through
+    if (state.bypassNextPop) {
+        state.bypassNextPop = false;
+        return;
+    }
+    // Already on the home screen: nothing for us to intercept
+    if (!state.subpanel) {
+        return;
+    }
+    // A prompt is already on screen: stay put instead of stacking another one
+    if (state.promptVisible) {
+        undoPop();
+        return;
+    }
+    // Blocked: stay put and explain why
+    if (state.subpanel.backState === BackState$1.Blocked) {
+        undoPop();
+        showBlockedMessage();
+        return;
+    }
+    // Unsaved changes: stay put until the user confirms. The pop is undone
+    // asynchronously here, before awaiting the confirmation, so that the user
+    // remains in the subpanel while they decide
+    if (state.subpanel.backState === BackState$1.UnsavedChanges) {
+        undoPop();
+        (() => __awaiter(void 0, void 0, void 0, function* () {
+            if (yield askToAbandonChanges()) {
+                returnHome(true);
+            }
+        }))();
+        return;
+    }
+    // Normal: allow it. The browser already consumed the history entry, so there
+    // is nothing left for us to step over
+    returnHome(false);
+};
+/*------------------------------------------------------------------------*/
+/* ------------------------------ Controller ---------------------------- */
+/*------------------------------------------------------------------------*/
+/**
+ * Controller for driving back navigation from anywhere in the app. Requires
+ *   useBackButton to have been called in the top-level app
+ * @author Yuen Ler Chow
+ */
+const backButtonController = {
+    /**
+     * Call this when the user navigates to a child of the home screen (something
+     *   they can come back from)
+     * @author Yuen Ler Chow
+     */
+    onSubpanelEntered: () => {
+        getHandleGoHome();
+        state.subpanel = {
+            backState: BackState$1.Normal,
+        };
+        // Add a history entry to come back to, so that the next back navigation is
+        // intercepted instead of leaving the app
+        window.history.pushState(HISTORY_STATE_MARKER, '');
+    },
+    /**
+     * Send the user back to the home screen
+     * @author Yuen Ler Chow
+     * @param [force] if true, go home immediately without checking the subpanel
+     *   state. If falsy, nothing happens while blocked and confirmation is
+     *   required when there are unsaved changes
+     */
+    goHome: (force) => __awaiter(void 0, void 0, void 0, function* () {
+        var _e, _f;
+        getHandleGoHome();
+        // Unless the caller is forcing the navigation, the subpanel's state decides
+        // whether the user may leave: a blocked subpanel refuses and explains why,
+        // and one with unsaved changes leaves only if the user confirms
+        if (!force) {
+            // A prompt is already asking the user this same question
+            if (state.promptVisible) {
+                return;
+            }
+            if (((_e = state.subpanel) === null || _e === void 0 ? void 0 : _e.backState) === BackState$1.Blocked) {
+                yield showBlockedMessage();
+                return;
+            }
+            if (((_f = state.subpanel) === null || _f === void 0 ? void 0 : _f.backState) === BackState$1.UnsavedChanges) {
+                const confirmed = yield askToAbandonChanges();
+                if (!confirmed) {
+                    return;
+                }
+            }
+        }
+        returnHome(true);
+    }),
+    /**
+     * Set the state of the current subpanel, which determines what happens when
+     *   the user tries to go back. Ignored while on the home screen, where there
+     *   is no back navigation to describe
+     * @author Yuen Ler Chow
+     * @param newSubpanelState the new state of the subpanel
+     */
+    setSubpanelState: (newSubpanelState) => {
+        if (!state.subpanel) {
+            return;
+        }
+        state.subpanel.backState = newSubpanelState;
+    },
+    /**
+     * Set the confirmation message shown if the user tries to go back while there
+     *   are unsaved changes. Cleared upon returning to the home screen
+     * @author Yuen Ler Chow
+     * @param message the message to show
+     */
+    setCustomUnsavedChangesMessage: (message) => {
+        if (!state.subpanel) {
+            return;
+        }
+        state.subpanel.customUnsavedChangesMessage = message;
+    },
+    /**
+     * Set the message shown if the user tries to go back while blocked. Cleared
+     *   upon returning to the home screen
+     * @author Yuen Ler Chow
+     * @param message the message to show
+     */
+    setCustomBlockedMessage: (message) => {
+        if (!state.subpanel) {
+            return;
+        }
+        state.subpanel.customBlockedMessage = message;
+    },
+};
+/*------------------------------------------------------------------------*/
+/* --------------------------------- Hook ------------------------------- */
+/*------------------------------------------------------------------------*/
+/**
+ * Hook that makes the browser's back button navigate within the app instead of
+ *   leaving it. Call this once in your top-level app, then use
+ *   backButtonController to enter subpanels and describe their state.
+ *
+ * Assumes a single level of navigation: one home screen plus subpanels that the
+ *   user returns home from.
+ * @author Yuen Ler Chow
+ * @param handleGoHomeFunc handler that performs the app state changes required
+ *   to return to the home screen
+ */
+const useBackButton = (handleGoHomeFunc) => {
+    // Store the handler on every render so that the listener below, which is only
+    // registered once, always calls the app's current version of it
+    state.handleGoHome = handleGoHomeFunc;
+    // The popstate listener has to be attached to the window, which is outside of
+    // React, so an effect is used to add it when the app mounts and remove it if
+    // the app ever unmounts. The empty dependency array keeps this to a single
+    // listener for the lifetime of the app instead of one per render
+    useEffect(() => {
+        // Mark the current entry as the home entry
+        window.history.replaceState(HISTORY_STATE_MARKER, '');
+        window.addEventListener('popstate', handlePopState);
+        return () => {
+            window.removeEventListener('popstate', handlePopState);
+            // Clear the static state so that a remount starts from scratch
+            state = {
+                promptVisible: false,
+                bypassNextPop: false,
+            };
+        };
+    }, []);
+};
+
 /*------------------------------------------------------------------------*/
 /* ------------------------------- Caching ------------------------------ */
 /*------------------------------------------------------------------------*/
@@ -14787,5 +15068,5 @@ const isSelectAdmin = () => __awaiter(void 0, void 0, void 0, function* () {
     }
 });
 
-export { AppWrapper, AutoscrollToBottomContainer, ButtonInputGroup, CSVDownloadButton, CheckboxButton, CopiableBox, DBEntryFieldType$1 as DBEntryFieldType, DBEntryManagerPanel, Drawer, Dropdown, DropdownItemType$1 as DropdownItemType, DynamicWord, ErrorBox, FakeProgressBar, IntelliTable, ItemPicker, LoadingSpinner, LogReviewer, Modal, ModalButtonType$1 as ModalButtonType, ModalSize$1 as ModalSize, ModalType$1 as ModalType, MultiSwitch, PopFailureMark, PopPendingMark, PopSuccessMark, ProgressBar, ProgressBarSize$1 as ProgressBarSize, RadioButton, SimpleDateChooser, SimpleMonthChooser, SimpleTimeChooser, TabBox, ToggleSwitch, Tooltip, Variant$1 as Variant, addFatalErrorHandler, alert, canReviewLogs, combineClassNames, confirm, initClient, isMobileOrTablet, isSelectAdmin, leaveToURL, logClientEvent, makeLinksClickable, prompt, setClientEventMetadataPopulator, showFatalError, stubServerEndpoint, useForceRender, visitServerEndpoint };
+export { AppWrapper, AutoscrollToBottomContainer, BackState$1 as BackState, ButtonInputGroup, CSVDownloadButton, CheckboxButton, CopiableBox, DBEntryFieldType$1 as DBEntryFieldType, DBEntryManagerPanel, Drawer, Dropdown, DropdownItemType$1 as DropdownItemType, DynamicWord, ErrorBox, FakeProgressBar, IntelliTable, ItemPicker, LoadingSpinner, LogReviewer, Modal, ModalButtonType$1 as ModalButtonType, ModalSize$1 as ModalSize, ModalType$1 as ModalType, MultiSwitch, PopFailureMark, PopPendingMark, PopSuccessMark, ProgressBar, ProgressBarSize$1 as ProgressBarSize, RadioButton, SimpleDateChooser, SimpleMonthChooser, SimpleTimeChooser, TabBox, ToggleSwitch, Tooltip, Variant$1 as Variant, addFatalErrorHandler, alert, backButtonController, canReviewLogs, combineClassNames, confirm, initClient, isMobileOrTablet, isSelectAdmin, leaveToURL, logClientEvent, makeLinksClickable, prompt, setClientEventMetadataPopulator, showFatalError, stubServerEndpoint, useBackButton, useForceRender, visitServerEndpoint };
 //# sourceMappingURL=index.js.map