@visns-studio/visns-components 6.3.0 → 6.3.2

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.2",
     "description": "Various packages to assist in the development of our Custom Applications.",
     "main": "src/index.js",
     "files": [

package/src/components/DataGrid.jsx

@@ -4630,44 +4630,37 @@ const DataGrid = forwardRef(
 
                 {/* Opt-in colour legend (config key `legend`: array of
                     {colour, label}); entries without a colour render as
-                    plain lead-in text */}
+                    plain lead-in text.
+
+                    Styling lives in DataGrid.module.scss (`.legend` and
+                    friends) rather than inline, so a consuming project can
+                    actually reach it — see the notes there. The only inline
+                    style left is the swatch's own fill, which is data from
+                    the config rather than a design decision. */}
                 {Array.isArray(legend) && legend.length > 0 && (
-                    <div
-                        style={{
-                            display: 'flex',
-                            flexWrap: 'wrap',
-                            alignItems: 'center',
-                            gap: '14px',
-                            padding: '6px 4px 8px',
-                            fontSize: '0.8rem',
-                            color: '#555',
-                        }}
-                    >
-                        {legend.map((item, index) => (
-                            <span
-                                key={index}
-                                style={{
-                                    display: 'inline-flex',
-                                    alignItems: 'center',
-                                    gap: '6px',
-                                }}
-                            >
-                                {(item.colour || item.color) && (
-                                    <span
-                                        style={{
-                                            width: '14px',
-                                            height: '14px',
-                                            borderRadius: '3px',
-                                            backgroundColor:
-                                                item.colour || item.color,
-                                            display: 'inline-block',
-                                            flexShrink: 0,
-                                        }}
-                                    />
-                                )}
-                                {item.label}
-                            </span>
-                        ))}
+                    <div className={styles.legend}>
+                        {legend.map((item, index) => {
+                            const swatch = item.colour || item.color;
+
+                            return (
+                                <span
+                                    key={index}
+                                    className={
+                                        swatch
+                                            ? styles.legendItem
+                                            : `${styles.legendItem} ${styles.legendLead}`
+                                    }
+                                >
+                                    {swatch && (
+                                        <span
+                                            className={styles.legendSwatch}
+                                            style={{ backgroundColor: swatch }}
+                                        />
+                                    )}
+                                    {item.label}
+                                </span>
+                            );
+                        })}
                     </div>
                 )}
 

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/DataGrid.module.scss

@@ -526,6 +526,94 @@
     justify-content: flex-end;
 }
 
+/* ============================================================================
+   Colour legend
+   ----------------------------------------------------------------------------
+   The opt-in caption above the grid (config key `legend`: an array of
+   `{ colour | color, label }`, where an entry carrying no colour renders as
+   lead-in text introducing the swatches after it).
+
+   This was inline styles on the elements themselves — `fontSize: '0.8rem'`,
+   `color: '#555'`, a hardcoded 14px swatch, `padding: '6px 4px 8px'`. Inline
+   styles are unreachable from a consuming project's stylesheet, so the one
+   thing a legend needs to be — tuned to the app it sits in — was the one
+   thing it could not be. It was also set off any scale in the library: 0.8rem
+   falls between two steps of the type ramp, and #555 is a grey that appears
+   nowhere else.
+
+   It is a caption for the table below it, so it is set as one: the same
+   `--font-size-xs`, `--muted-color` and `--font-weight-semibold` the grid's
+   own header row uses, so the two label rows stacked above the data read as
+   one family. It deliberately stops short of that header's uppercase and
+   0.06em tracking — legend labels are sentences ("No Goods Received entered
+   yet"), not column names, and setting a sentence in caps would undo the
+   quiet the rest of this is after.
+
+   Density hooks, following the `--nav-*` set documented at the top of
+   Navigation.module.scss: every declaration below is written
+   `var(--hook, <the value it always had>)`, so an unset hook is a no-op and a
+   project retunes from `:root` with no fork, no prop and no class of its own.
+   The plant-floor tablet case is the one that needs them — 12px is small when
+   the screen is at arm's length on a bench.
+
+     --grid-legend-font-size    label type size.
+                                default: var(--font-size-xs, 0.75rem)
+     --grid-legend-gap          space between entries along a line.
+                                default: var(--spacing-md, 1rem)
+     --grid-legend-swatch-size  the colour chip.        default: 0.875rem (14px)
+   ========================================================================= */
+
+.legend {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    /* Row gap and column gap differ on purpose: a legend that wraps (despatch
+       runs to seven entries) needs its lines closer together than its entries
+       are along a line, or the wrapped rows read as separate captions. */
+    gap: var(--spacing-sm, 0.5rem)
+        var(--grid-legend-gap, var(--spacing-md, 1rem));
+    /* A caption belongs to the thing it describes, so it sits nearer the grid
+       than the toolbar row above it — which is also what stops it crowding
+       that row, the complaint this change came from. No horizontal padding:
+       `.dataGridContainer` has none either, so the caption starts on the
+       grid's own left edge rather than floating 4px off it. */
+    margin: var(--spacing-md, 1rem) 0 var(--spacing-sm, 0.5rem);
+    padding: 0;
+    font-size: var(--grid-legend-font-size, var(--font-size-xs, 0.75rem));
+    line-height: 1.4;
+    color: var(--muted-color, #6b7688);
+}
+
+.legendItem {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--spacing-xs, 0.25rem);
+}
+
+/* The lead-in entry: a legend line with no colour of its own, labelling the
+   swatches that follow. Weight and a darker ink rather than a different size,
+   so it introduces the row without breaking its line. */
+.legendLead {
+    font-weight: var(--font-weight-semibold, 600);
+    color: var(--paragraph-color, #374151);
+}
+
+.legendSwatch {
+    width: var(--grid-legend-swatch-size, 0.875rem);
+    height: var(--grid-legend-swatch-size, 0.875rem);
+    flex-shrink: 0;
+    display: inline-block;
+    border-radius: var(--radius-sm, 6px);
+    /* These are row tints, so they are pale by design — #FFEAEA has no edge
+       of its own against a white page and the swatch dissolves into it. A
+       low-alpha ink hairline gives every chip its shape back while staying
+       invisible against the darker ones. `--border-color` is the wrong token
+       here: it is tuned to be barely there on a white surface, which is
+       exactly where it is needed most. */
+    border: 1px solid rgba(var(--paragraph-color-rgb, 34, 30, 51), 0.18);
+    box-sizing: border-box;
+}
+
 /* Date field styling for uniform width */
 :global {
     // Target date cells specifically

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;