@visns-studio/visns-components 6.3.0 → 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.3.0",
+    "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

@@ -184,6 +184,15 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
      */
     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);
@@ -1376,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);
         }
@@ -1850,6 +1862,68 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
     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.
      *
@@ -1867,6 +1941,11 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             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
@@ -2100,8 +2179,20 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             return;
         }
 
-        setUnsavedChanges(
-            snapshotOf(data.label, data.detail) !== savedSnapshotRef.current
+        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]);
 
@@ -2340,7 +2431,7 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                     items: [
                         '<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',
+                        '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',
@@ -2714,10 +2805,15 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                                         ? styles.saveStateDirty
                                         : styles.saveStateClean
                                 }`}
+                                aria-live="polite"
                             >
-                                {unsavedChanges
-                                    ? 'Unsaved changes'
-                                    : 'All changes saved'}
+                                {!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. */}
@@ -2741,10 +2837,20 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                                 questions looked like the one that renames the
                                 form. It belongs out here, beside the work. */}
                             <button
-                                className={`${styles.btn} ${styles.btnPrimary}`}
+                                className={`${styles.btn} ${
+                                    styles.btnPrimary
+                                } ${
+                                    unsavedChanges
+                                        ? styles.btnSaveDirty
+                                        : styles.btnSaveClean
+                                }`}
                                 onClick={handleSubmit}
                                 data-tooltip-id="system-tooltip"
-                                data-tooltip-content="Store this template. Question windows only stage changes on screen."
+                                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>

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

@@ -833,8 +833,22 @@ select:not(:placeholder-shown) + .fi__span {
     }
 }
 
+/* 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: #b45309;
+    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 {
@@ -846,6 +860,70 @@ select:not(:placeholder-shown) + .fi__span {
     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;