@visns-studio/visns-components 6.2.1 → 6.3.1

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.1",
     "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,33 @@ 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);
+    /** How many questions differ from the stored version, for the indicator. */
+    const [unsavedCount, setUnsavedCount] = useState(0);
+    /**
+     * Whether the "this is not stored yet" notice has already been given since
+     * the last successful save. Once per unsaved streak: the first Apply is
+     * where the misunderstanding happens, and a toast on every Apply after that
+     * would train people to dismiss it without reading.
+     */
+    const stagedNoticeShownRef = useRef(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;
@@ -1358,8 +1385,11 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
         let errorMessage = validateField(field);
 
         if (errorMessage === '') {
+            const isNew = modalType.type === 'create';
+
             saveFieldData(field);
             handleCloseModal();
+            announceStagedChange(isNew);
         } else {
             displayErrorMessage(errorMessage);
         }
@@ -1397,6 +1427,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 +1858,101 @@ 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 ?? [] });
+
+    /**
+     * How many separate edits are waiting to be stored, counted by question.
+     *
+     * A number is worth more than "Unsaved changes" alone — it tells somebody
+     * who stepped away how much they stand to lose. Counted by field id, so an
+     * added, a reworded and a deleted question are three, while re-ordering the
+     * same questions is none of them. That last case is not a miscount: the
+     * order is written to the server the moment it changes, so a pure re-order
+     * shows as dirty for only as long as that request is in flight, and the
+     * wording below falls back to the unnumbered phrase.
+     */
+    const countUnsavedChanges = (baseline, label, detail) => {
+        let count = (baseline.label ?? '') === (label ?? '') ? 0 : 1;
+
+        const stored = new Map(
+            (baseline.detail ?? []).map((field) => [
+                field.id,
+                JSON.stringify(field),
+            ])
+        );
+        const present = new Set();
+
+        (detail ?? []).forEach((field) => {
+            present.add(field.id);
+
+            if (stored.get(field.id) !== JSON.stringify(field)) {
+                count += 1;
+            }
+        });
+
+        stored.forEach((_encoded, id) => {
+            if (!present.has(id)) {
+                count += 1;
+            }
+        });
+
+        return count;
+    };
+
+    /**
+     * Say, at the moment it is least obvious, that Apply stored nothing.
+     *
+     * The question window closes and the new question appears in the list,
+     * which looks exactly like a save. This is the one place where saying so
+     * costs nothing and lands while the user is still looking.
+     */
+    const announceStagedChange = (isNew) => {
+        if (stagedNoticeShownRef.current) {
+            return;
+        }
+
+        stagedNoticeShownRef.current = true;
+
+        toast.info(
+            <div>
+                {isNew ? 'Question added' : 'Question updated'} — this is on
+                screen only. Tap <strong>Save Template</strong> to store it.
+            </div>,
+            { toastId: 'fb-staged-change', autoClose: 6000 }
+        );
+    };
+
+    /**
+     * 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
+        );
+
+        // The reminder is earned again by the next unsaved streak. Anyone who
+        // has just stored their work has demonstrably understood the flow, and
+        // will still be told the next time they walk into it.
+        stagedNoticeShownRef.current = false;
+
+        // 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 +2016,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 +2055,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 +2101,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 +2132,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 +2167,59 @@ 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;
+        }
+
+        const dirty =
+            snapshotOf(data.label, data.detail) !== savedSnapshotRef.current;
+
+        setUnsavedChanges(dirty);
+        // Only worth counting when something is outstanding, so a clean screen
+        // never pays for parsing the baseline.
+        setUnsavedCount(
+            dirty
+                ? countUnsavedChanges(
+                      JSON.parse(savedSnapshotRef.current),
+                      data.label,
+                      data.detail
+                  )
+                : 0
+        );
+    }, [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 +2429,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)',
+                        'While anything is waiting, the button turns amber and the label beside it counts what you would lose — the browser warns you as well 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 +2796,25 @@ 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
+                                }`}
+                                aria-live="polite"
+                            >
+                                {!unsavedChanges
+                                    ? 'All changes saved'
+                                    : unsavedCount > 0
+                                      ? `${unsavedCount} unsaved change${
+                                            unsavedCount === 1 ? '' : 's'
+                                        }`
+                                      : 'Unsaved changes'}
+                            </span>
                             {/* Nothing to author on a dynamic template, but
                                 Edit Form stays so it can still be renamed. */}
                             {!dynamicFields && (
@@ -2582,6 +2831,29 @@ 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
+                                } ${
+                                    unsavedChanges
+                                        ? styles.btnSaveDirty
+                                        : styles.btnSaveClean
+                                }`}
+                                onClick={handleSubmit}
+                                data-tooltip-id="system-tooltip"
+                                data-tooltip-content={
+                                    unsavedChanges
+                                        ? 'You have changes that are only on screen. Tap to store them.'
+                                        : 'Everything on this screen is stored.'
+                                }
+                            >
+                                Save Template
+                            </button>
                         </div>
                     </div>
                 </div>
@@ -3399,11 +3671,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,128 @@ 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;
+    }
+}
+
+/* Amber, pilled and bolder than its calm twin. The indicator, the dot and the
+   Save Template button all sit on the same warning hue on purpose: one state,
+   said three times, so it cannot be read as decoration. */
+.saveStateDirty {
+    color: #92400e;
+    font-weight: 700;
+    padding: 3px 10px;
+    border-radius: 999px;
+    background: rgba(245, 158, 11, 0.16);
+    border: 1px solid rgba(180, 83, 9, 0.35);
+
+    &::before {
+        background: #d97706;
+        box-shadow: 0 0 0 0 rgba(217, 119, 6, 0.6);
+        animation: fbSaveDot 2s ease-in-out infinite;
+    }
+}
+
+.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);
+}
+
+/* Nothing to save: present and findable, but not competing for attention. */
+.btnSaveClean {
+    opacity: 0.9;
+}
+
+/**
+ * Something to save. Amber overrides the shared primary fill, and the ring
+ * breathes so the button reads as waiting on the user rather than as one more
+ * blue button in a row of blue buttons.
+ */
+.btnSaveDirty {
+    background: #d97706 !important;
+    border-color: #b45309 !important;
+    color: #fff !important;
+    font-weight: 700;
+    box-shadow:
+        0 0 0 2px rgba(217, 119, 6, 0.45),
+        0 4px 14px rgba(180, 83, 9, 0.35);
+    animation: fbSaveNudge 2s ease-in-out infinite;
+
+    &:hover:not(:disabled) {
+        background: #b45309 !important;
+        border-color: #92400e !important;
+        color: #fff !important;
+    }
+}
+
+@keyframes fbSaveNudge {
+    0%,
+    100% {
+        box-shadow:
+            0 0 0 2px rgba(217, 119, 6, 0.45),
+            0 4px 14px rgba(180, 83, 9, 0.35);
+        transform: scale(1);
+    }
+
+    50% {
+        box-shadow:
+            0 0 0 7px rgba(217, 119, 6, 0),
+            0 6px 18px rgba(180, 83, 9, 0.45);
+        transform: scale(1.035);
+    }
+}
+
+@keyframes fbSaveDot {
+    0%,
+    100% {
+        box-shadow: 0 0 0 0 rgba(217, 119, 6, 0.6);
+    }
+
+    50% {
+        box-shadow: 0 0 0 5px rgba(217, 119, 6, 0);
+    }
+}
+
+/* Movement is the enhancement, never the message: the amber fill, the ring and
+   the wording all survive on their own for anyone who asked for stillness. */
+@media (prefers-reduced-motion: reduce) {
+    .btnSaveDirty,
+    .saveStateDirty::before {
+        animation: none;
+    }
+}
+
+/* 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 +1459,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 +2175,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 +2601,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 +2750,6 @@ select:not(:placeholder-shown) + .fi__span {
 
 /* ---- compact rows ---- */
 
-
-
-
 .duplicateBtn {
     display: flex;
     align-items: center;
@@ -2705,6 +2830,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;