@visns-studio/visns-components 6.2.1 → 6.3.0

package/package.json

@@ -91,7 +91,7 @@
         "react-dom": "^17.0.0 || ^18.0.0"
     },
     "name": "@visns-studio/visns-components",
-    "version": "6.2.1",
+    "version": "6.3.0",
     "description": "Various packages to assist in the development of our Custom Applications.",
     "main": "src/index.js",
     "files": [

package/src/components/generic/GenericFormBuilder.jsx

@@ -168,6 +168,24 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
      * tab itself has already replaced.
      */
     const expectedDetailHashRef = useRef(null);
+
+    /**
+     * The `{label, detail}` the server is believed to hold, as a comparable
+     * string.
+     *
+     * Every authoring action on this screen — adding a question, rewording an
+     * option, changing a size — only moves React state. Nothing reaches the
+     * server until the template itself is saved, and until this ref existed
+     * there was no way to tell "on screen" from "stored": a tab could be closed
+     * on an afternoon's work and say nothing about it.
+     *
+     * Null until the first load lands. Before that there is no baseline, and
+     * everything would compare as changed.
+     */
+    const savedSnapshotRef = useRef(null);
+    const [unsavedChanges, setUnsavedChanges] = useState(false);
+    /** Bumped whenever the baseline moves, so the comparison below re-runs. */
+    const [savedBaselineTick, setSavedBaselineTick] = useState(0);
     const lockEnabled = Boolean(optimisticLock);
     const lockSchemaVersion =
         optimisticLock?.schemaVersion ?? DEFAULT_LOCK_SCHEMA_VERSION;
@@ -1397,6 +1415,20 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             (!field.options || field.options.length === 0)
         ) {
             errors.push('Please add options for the dropdown.');
+        } else if (
+            /**
+             * A checkbox with no options renders as a bare label with nothing
+             * to tick. Harmless-looking in the builder, and fatal in the field:
+             * marked required, it cannot be answered, so the form it belongs to
+             * can never be submitted. Dropdowns have always been held to this;
+             * checkboxes were simply missed.
+             */
+            field.type === 'checkbox' &&
+            (!field.options || field.options.length === 0)
+        ) {
+            errors.push(
+                'Please add at least one option for the checkbox — a checkbox with no options cannot be answered.'
+            );
         } else if (
             field.type === 'table_text' &&
             (!field.options || field.options.length === 0)
@@ -1814,6 +1846,34 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
         );
     };
 
+    /** The comparable form of the two things this screen actually stores. */
+    const snapshotOf = (label, detail) =>
+        JSON.stringify({ label: label ?? '', detail: detail ?? [] });
+
+    /**
+     * Re-anchor the unsaved-changes baseline on what the server now holds.
+     *
+     * Takes a partial: the sort endpoint writes `detail` alone and leaves the
+     * label as it was, so rebuilding the whole baseline from the current
+     * on-screen `data` would quietly adopt an unsaved rename as "stored".
+     */
+    const markSaved = ({ label, detail } = {}) => {
+        const previous = savedSnapshotRef.current
+            ? JSON.parse(savedSnapshotRef.current)
+            : {};
+
+        savedSnapshotRef.current = snapshotOf(
+            label === undefined ? previous.label : label,
+            detail === undefined ? previous.detail : detail
+        );
+
+        // Never `setUnsavedChanges(false)` directly: a partial save can leave
+        // something else still unsaved. Re-ordering writes `detail` and not the
+        // label, so declaring the screen clean here would lose a pending
+        // rename. Let the one comparison decide.
+        setSavedBaselineTick((tick) => tick + 1);
+    };
+
     /**
      * "Somebody else got here first", in the only words that help.
      *
@@ -1877,6 +1937,10 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
 
                     if (res.data.error === '') {
                         await rememberDetailHash(data.id, savedDetail);
+                        markSaved({
+                            label: data.label,
+                            detail: savedDetail,
+                        });
 
                         toast.success(
                             "You have successfully updated the form's detail."
@@ -1912,7 +1976,31 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                     return;
                 }
 
+                /**
+                 * Suppressing the shared handler's toast made this branch the
+                 * only voice the user has, so it must never be silent. It used
+                 * to `return` here, which turned an expired session (401
+                 * `Unauthenticated.`) — or any error body carrying neither
+                 * `errors` nor `message` — into a save that looked like it had
+                 * worked: nothing stored, and nothing said about it.
+                 */
                 if (err?.response) {
+                    const status = err.response.status;
+                    const expired =
+                        status === 401 || message === 'Unauthenticated.';
+
+                    toast.error(
+                        <div>
+                            <strong>Nothing was saved.</strong>{' '}
+                            {expired
+                                ? 'Your session has expired. Sign in again in another tab, then come back and save — your changes are still on screen.'
+                                : `The server refused the save${
+                                      status ? ` (error ${status})` : ''
+                                  }. Your changes are still on screen — try again, and report this if it keeps happening.`}
+                        </div>,
+                        { autoClose: false }
+                    );
+
                     return;
                 }
             }
@@ -1934,6 +2022,10 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             // The version this tab is editing from. Everything the guard does
             // is measured against this moment.
             await rememberDetailHash(res.data?.id, res.data?.detail);
+            markSaved({
+                label: res.data?.label,
+                detail: res.data?.detail,
+            });
         } catch (err) {
             toast.error(`Error: ${err}`);
         }
@@ -1961,6 +2053,10 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             // here — but leaving the hash behind would make the next Save
             // report a collision this tab caused itself.
             await rememberDetailHash(data.id, savedDetail);
+
+            // Re-ordering is the one authoring action that reaches the server
+            // on its own, so the unsaved-changes baseline has to follow it too.
+            markSaved({ detail: savedDetail });
         } catch (err) {
             toast.error(`Error: ${err}`);
         }
@@ -1992,6 +2088,47 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
         fetchRoles();
     }, []);
 
+    /**
+     * Is what is on screen different from what is stored?
+     *
+     * Compared against the baseline rather than tracked per-action, so it
+     * cannot drift: undoing a change by hand correctly reports "all changes
+     * saved" again, and no authoring path can forget to raise the flag.
+     */
+    useEffect(() => {
+        if (savedSnapshotRef.current === null) {
+            return;
+        }
+
+        setUnsavedChanges(
+            snapshotOf(data.label, data.detail) !== savedSnapshotRef.current
+        );
+    }, [data, savedBaselineTick]);
+
+    /**
+     * The browser's own "leave site?" prompt, and only while there is something
+     * to lose. Last line of defence for the failure this screen is prone to: a
+     * question window's button reads as final, so a template can be closed in
+     * the belief that its questions were filed.
+     */
+    useEffect(() => {
+        if (!unsavedChanges) {
+            return undefined;
+        }
+
+        const warnBeforeLeaving = (event) => {
+            event.preventDefault();
+            event.returnValue = '';
+
+            return '';
+        };
+
+        window.addEventListener('beforeunload', warnBeforeLeaving);
+
+        return () =>
+            window.removeEventListener('beforeunload', warnBeforeLeaving);
+    }, [unsavedChanges]);
+
     /* ---------------------------------------------------------------- */
     /* Guided help                                                       */
     /* ---------------------------------------------------------------- */
@@ -2201,8 +2338,10 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                     border: '#dc2626',
                     text: '#991b1b',
                     items: [
-                        '<strong>Save</strong> inside a question window only adds it to the list on screen — nothing is stored yet',
-                        'To store the template, click <strong>Edit Form</strong> (bottom right) and then <strong>Save</strong>',
+                        '<strong>Apply</strong> inside a question window only adds it to the list on screen — nothing is stored yet',
+                        'To store the template, click <strong>Save Template</strong> (bottom right)',
+                        'The label beside those buttons reads <strong>Unsaved changes</strong> until you do, and the browser warns you if you try to leave',
+                        '<strong>Edit Form</strong> is only for renaming the template',
                         'Moving a question saves the whole template straight away, so the order is never lost',
                         'If someone else changed this template while you had it open, you are told nothing was saved — reload the page before saving again, or your changes would undo theirs',
                     ],
@@ -2566,6 +2705,20 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                             )}
                         </div>
                         <div className={styles.polActions}>
+                            {/* The only honest answer to "have my changes been
+                                stored?". Everything else on this screen edits a
+                                copy held in the browser. */}
+                            <span
+                                className={`${styles.saveState} ${
+                                    unsavedChanges
+                                        ? styles.saveStateDirty
+                                        : styles.saveStateClean
+                                }`}
+                            >
+                                {unsavedChanges
+                                    ? 'Unsaved changes'
+                                    : 'All changes saved'}
+                            </span>
                             {/* Nothing to author on a dynamic template, but
                                 Edit Form stays so it can still be renamed. */}
                             {!dynamicFields && (
@@ -2582,6 +2735,19 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                             >
                                 Edit Form
                             </button>
+                            {/* Was reachable only through Edit Form — a window
+                                titled "Update Form Detail" showing nothing but
+                                the label, so the action that stores the
+                                questions looked like the one that renames the
+                                form. It belongs out here, beside the work. */}
+                            <button
+                                className={`${styles.btn} ${styles.btnPrimary}`}
+                                onClick={handleSubmit}
+                                data-tooltip-id="system-tooltip"
+                                data-tooltip-content="Store this template. Question windows only stage changes on screen."
+                            >
+                                Save Template
+                            </button>
                         </div>
                     </div>
                 </div>
@@ -3399,11 +3565,23 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                                     <div
                                         className={`${styles.formItem} ${styles.fwItem} ${styles.lastItem}`}
                                     >
+                                        {/* This window has never stored
+                                            anything — it edits the copy held in
+                                            the browser. Calling its button
+                                            "Save" was the whole reason people
+                                            left the screen believing their work
+                                            had been filed. */}
+                                        <p className={styles.applyHint}>
+                                            Adds this question to the list on
+                                            screen. Use{' '}
+                                            <strong>Save Template</strong> to
+                                            store it.
+                                        </p>
                                         <button
                                             className={`${styles.btn}`}
                                             onClick={handleSaveField}
                                         >
-                                            Save
+                                            Apply
                                         </button>
                                     </div>
                                 </form>

package/src/components/styles/GenericFormBuilder.module.scss

@@ -643,7 +643,8 @@ select:not(:placeholder-shown) + .fi__span {
     overflow: visible;
     position: relative;
     z-index: 100;
-    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.15),
+    box-shadow:
+        0 20px 60px rgba(0, 0, 0, 0.15),
         0 0 0 1px rgba(var(--primary-rgb), 0.06);
 }
 
@@ -786,9 +787,6 @@ select:not(:placeholder-shown) + .fi__span {
 
 /* Adding btn class */
 
-
-
-
 /* Floating action buttons */
 .polActions {
     position: fixed;
@@ -801,9 +799,11 @@ select:not(:placeholder-shown) + .fi__span {
     background: rgba(255, 255, 255, 0.95);
     padding: 10px 14px;
     border-radius: 12px;
-    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.12),
+    box-shadow:
+        0 4px 20px rgba(0, 0, 0, 0.12),
         0 0 0 1px rgba(var(--primary-rgb), 0.08);
     backdrop-filter: blur(8px);
+    align-items: center;
 
     button {
         display: block;
@@ -814,6 +814,50 @@ select:not(:placeholder-shown) + .fi__span {
     }
 }
 
+/* Stored or not — the one thing this screen never used to say out loud. */
+.saveState {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 0 6px;
+    font-size: 0.8rem;
+    font-weight: 600;
+    white-space: nowrap;
+
+    &::before {
+        content: '';
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+        background: currentColor;
+    }
+}
+
+.saveStateDirty {
+    color: #b45309;
+}
+
+.saveStateClean {
+    color: #15803d;
+}
+
+/* The save that actually writes, weighted so it reads as the end of the job. */
+.btnPrimary {
+    box-shadow: 0 0 0 2px rgba(var(--primary-rgb), 0.35);
+}
+
+/* Sits under the question window's Apply, where the misunderstanding happens. */
+.applyHint {
+    flex: 1;
+    align-self: center;
+    margin: 0;
+    padding-right: 1rem;
+    font-size: 0.78rem;
+    line-height: 1.35;
+    color: var(--text-color-light, #6b7280);
+    text-align: left;
+}
+
 .fwItem {
     flex-basis: 100%;
 }
@@ -1337,6 +1381,12 @@ select:not(:placeholder-shown) + .fi__span {
 .dragHandle {
     color: var(--primary-color) !important;
     cursor: grab;
+    /* Same reason as .cGrip: on iPadOS the browser treats a press-and-move on
+       this handle as a scroll unless the element opts out, so the drag never
+       activates and reordering is silently unavailable. */
+    touch-action: none;
+    -webkit-user-select: none;
+    user-select: none;
     padding: 4px;
     border-radius: 6px;
     background: white;
@@ -2047,7 +2097,8 @@ select:not(:placeholder-shown) + .fi__span {
     border-radius: 12px;
     padding: 1.25rem 1.5rem;
     width: 280px;
-    box-shadow: 0 16px 48px rgba(0, 0, 0, 0.18),
+    box-shadow:
+        0 16px 48px rgba(0, 0, 0, 0.18),
         0 0 0 1px rgba(var(--primary-rgb), 0.08);
 
     h3 {
@@ -2472,7 +2523,6 @@ select:not(:placeholder-shown) + .fi__span {
     margin-right: -1.15rem !important;
 }
 
-
 /* The header and search span both columns; only the rail and canvas sit
    side by side. */
 
@@ -2622,9 +2672,6 @@ select:not(:placeholder-shown) + .fi__span {
 
 /* ---- compact rows ---- */
 
-
-
-
 .duplicateBtn {
     display: flex;
     align-items: center;
@@ -2705,6 +2752,12 @@ select:not(:placeholder-shown) + .fi__span {
     align-items: center;
     color: rgba(var(--paragraph-rgb), 0.4);
     cursor: grab;
+    /* dnd-kit's PointerSensor cannot start a drag from an element the browser
+       has already claimed for scrolling. Without this the grip does nothing at
+       all on a touch screen — the page just scrolls under the finger. */
+    touch-action: none;
+    -webkit-user-select: none;
+    user-select: none;
 
     &:active {
         cursor: grabbing;