dce-reactkit 5.0.8 → 5.0.10

package/dist/cjs/index.js

@@ -2886,22 +2886,23 @@ const NestableItemList = (props) => {
                 onChanged(changeChecked(item.id, checked, items));
             }, ariaLabel: `Select ${accessibleName}`, checkedVariant: Variant$1.Light, uncheckedVariant: Variant$1.Light }));
         return (React__default["default"].createElement("div", { key: item.id },
-            React__default["default"].createElement("span", { className: "NestableItemList-dropdown-button-container d-inline-block", style: {
-                    minWidth: '2rem',
-                } }, item.isGroup && (React__default["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["default"].createElement(reactFontawesome.FontAwesomeIcon, { icon: childExpanded[item.id] ? freeSolidSvgIcons.faChevronDown : freeSolidSvgIcons.faChevronRight })))),
-            item.tooltip
-                ? (React__default["default"].createElement(Tooltip, { text: item.tooltip },
-                    React__default["default"].createElement("span", { className: "d-inline-block" }, checkbox)))
-                : checkbox,
+            React__default["default"].createElement("div", { className: "NestableItemList-item d-flex align-items-center" },
+                React__default["default"].createElement("span", { className: "NestableItemList-dropdown-button-container", style: {
+                        minWidth: '2rem',
+                    } }, item.isGroup && (React__default["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["default"].createElement(reactFontawesome.FontAwesomeIcon, { icon: childExpanded[item.id] ? freeSolidSvgIcons.faChevronDown : freeSolidSvgIcons.faChevronRight })))),
+                item.tooltip
+                    ? (React__default["default"].createElement(Tooltip, { text: item.tooltip },
+                        React__default["default"].createElement("span", { className: "d-inline-block" }, checkbox)))
+                    : checkbox),
             (item.isGroup && childExpanded[item.id]) && (React__default["default"].createElement("div", { className: "NestableItemList-children-container", style: {
                     paddingLeft: '2.2rem',
                 } },
@@ -14777,6 +14778,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
+    React.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 ------------------------------ */
 /*------------------------------------------------------------------------*/
@@ -14905,6 +15186,10 @@ Object.defineProperty(exports, 'compareArraysByProp', {
     enumerable: true,
     get: function () { return dceCommonkit.compareArraysByProp; }
 });
+Object.defineProperty(exports, 'convertDateKeyToDateInfo', {
+    enumerable: true,
+    get: function () { return dceCommonkit.convertDateKeyToDateInfo; }
+});
 Object.defineProperty(exports, 'everyAsync', {
     enumerable: true,
     get: function () { return dceCommonkit.everyAsync; }
@@ -15047,6 +15332,7 @@ Object.defineProperty(exports, 'waitMs', {
 });
 exports.AppWrapper = AppWrapper;
 exports.AutoscrollToBottomContainer = AutoscrollToBottomContainer;
+exports.BackState = BackState$1;
 exports.ButtonInputGroup = ButtonInputGroup;
 exports.CSVDownloadButton = CSVDownloadButton;
 exports.CheckboxButton = CheckboxButton;
@@ -15083,6 +15369,7 @@ exports.Tooltip = Tooltip;
 exports.Variant = Variant$1;
 exports.addFatalErrorHandler = addFatalErrorHandler;
 exports.alert = alert;
+exports.backButtonController = backButtonController;
 exports.canReviewLogs = canReviewLogs;
 exports.combineClassNames = combineClassNames;
 exports.confirm = confirm;
@@ -15096,6 +15383,7 @@ exports.prompt = prompt;
 exports.setClientEventMetadataPopulator = setClientEventMetadataPopulator;
 exports.showFatalError = showFatalError;
 exports.stubServerEndpoint = stubServerEndpoint;
+exports.useBackButton = useBackButton;
 exports.useForceRender = useForceRender;
 exports.visitServerEndpoint = visitServerEndpoint;
 //# sourceMappingURL=index.js.map