@visns-studio/visns-components 6.0.5 → 6.1.1

package/src/components/generic/GenericFormBuilder.jsx

@@ -50,18 +50,125 @@ import Breadcrumb from '../Breadcrumb';
 import CustomFetch from '../Fetch';
 import SketchConfig from '../sketch/json/config.json';
 import ConditionalDisplayEditor from './ConditionalDisplayEditor';
+import {
+    OutstandingOptionToggle,
+    OutstandingRuleHint,
+    applyOutstandingRule,
+    deriveOutstandingSelection,
+    isOutstandingConfigurable,
+    remapOutstandingWhen,
+    staleOutstandingIds,
+    summariseOutstandingRule,
+} from './OutstandingRuleEditor';
 
 import styles from '../styles/GenericFormBuilder.module.scss'; // Import the CSS module
 
+/**
+ * Optimistic locking for the builder — opt-in, and dormant without it.
+ *
+ * The builder's PUT has always been a blind overwrite: whatever the tab holds
+ * wins, however old it is. That is survivable while the only way to change a
+ * template is the builder itself, and stops being survivable the moment
+ * something else can rewrite one — a spreadsheet import, say — because a tab
+ * left open across the import silently undoes it on the next Save.
+ *
+ * The handle is a content hash of `detail`, declared by the writer as "this is
+ * the version I believe I am overwriting". Backends that understand it refuse
+ * the write with 409 when the row has moved on; backends that do not simply
+ * ignore an unknown field, which is why this ships behind a config flag rather
+ * than on for everybody: a model with `$guarded = []` would try to write it as
+ * a column.
+ *
+ * @see FormTemplate::expectDetailHash() and FormTemplateEnvelope::hashDetail()
+ *      in the Prime backend — the canonical encoding below is that method's
+ *      twin and must not drift from it.
+ */
+const DEFAULT_LOCK_SCHEMA_VERSION = 1;
+
+/**
+ * The content hash of a template's `detail`, computed exactly as the server
+ * computes it.
+ *
+ * The server hashes `json_encode(['schema_version' => N, 'id' => id,
+ * 'detail' => detail], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)`.
+ * `JSON.stringify` of the same values is byte-identical to that: both leave
+ * slashes and non-ASCII raw, both use the same short escapes, and `detail`
+ * arrived here as JSON so its key order and value types are already whatever
+ * PHP encoded. Verified against all 35 live templates before this shipped —
+ * every hash matched.
+ *
+ * Returns null rather than guessing when it cannot be computed (no SubtleCrypto
+ * outside a secure context, no numeric id yet). A null hash is simply not sent,
+ * which leaves the save exactly as unguarded as it was before — the wrong
+ * hash would reject every save, and a missing one rejects none.
+ */
+const detailContentHash = async (templateId, detail, schemaVersion) => {
+    const subtle = globalThis.crypto?.subtle;
+
+    if (!subtle || typeof templateId !== 'number') {
+        return null;
+    }
+
+    const canonical = JSON.stringify({
+        schema_version: schemaVersion,
+        id: templateId,
+        detail: detail ?? [],
+    });
+
+    try {
+        const digest = await subtle.digest(
+            'SHA-256',
+            new TextEncoder().encode(canonical)
+        );
+
+        return [...new Uint8Array(digest)]
+            .map((byte) => byte.toString(16).padStart(2, '0'))
+            .join('');
+    } catch (error) {
+        return null;
+    }
+};
+
 function GenericFormBuilder({ setting, urlParam, userProfile }) {
     const editorRef = useRef(null);
     const routeParams = useParams();
 
-    const { dynamicDropdowns, fetchUrl, fields, parentUrl, formTitle } =
-        setting;
+    const {
+        dynamicDropdowns,
+        fetchUrl,
+        fields,
+        parentUrl,
+        formTitle,
+        /**
+         * Opt-in, per-question "outstanding item" rules. Absent for every app
+         * that does not model outstanding items, in which case none of the
+         * `outstanding_when` handling below does anything at all.
+         */
+        outstandingItems,
+        /**
+         * Opt-in collision guard. `true`, or `{ schemaVersion: n }` when the
+         * backend's envelope version is not 1. Absent for every app whose
+         * backend does not understand `expected_detail_hash`, in which case
+         * nothing below sends one and the save is unchanged.
+         */
+        optimisticLock,
+    } = setting;
 
     const { dataId } = useParams();
     const [data, setData] = useState({});
+
+    /**
+     * The hash of the `detail` the server is believed to hold right now.
+     *
+     * Set from the load, and re-anchored after every save this tab makes — a
+     * hash describes one write, so leaving the load-time value in place would
+     * make the second save of a session compare against a version that this
+     * tab itself has already replaced.
+     */
+    const expectedDetailHashRef = useRef(null);
+    const lockEnabled = Boolean(optimisticLock);
+    const lockSchemaVersion =
+        optimisticLock?.schemaVersion ?? DEFAULT_LOCK_SCHEMA_VERSION;
     const [dataField, setDataField] = useState({
         id: '',
         label: '',
@@ -115,6 +222,17 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
         key: '',
     });
     const [modalFormShow, setModalFormShow] = useState(false);
+    /**
+     * The open field modal's outstanding-item switch. `touched` is false until
+     * the author actually flips one, and until then the displayed state is
+     * derived from the field on every render — so a brand-new question picks up
+     * the standard rule as soon as its answers exist, rather than being frozen
+     * at whatever was true when the modal opened.
+     */
+    const [outstandingRule, setOutstandingRule] = useState({
+        touched: false,
+        id: null,
+    });
     const [roles, setRoles] = useState([]);
     const [hoveredField, setHoveredField] = useState(null);
     const [activeId, setActiveId] = useState(null);
@@ -148,6 +266,37 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
      */
     const dynamicFields = data.field_source === 'dynamic';
 
+    /** Does the open field carry an editable outstanding-item rule at all? */
+    const outstandingEnabled = isOutstandingConfigurable(
+        outstandingItems,
+        dataField.type
+    );
+
+    /**
+     * Which answer currently has its "Outstanding" switch on. Always sanitised
+     * against the answers the field offers right now, so renaming or deleting
+     * an answer can never leave a dangling id to be saved.
+     */
+    const outstandingSelection = useMemo(() => {
+        if (!outstandingEnabled) return null;
+
+        const candidate = outstandingRule.touched
+            ? outstandingRule.id
+            : deriveOutstandingSelection(dataField);
+
+        return (dataField.options || []).some(
+            (option) => option && option.id === candidate
+        )
+            ? candidate
+            : null;
+    }, [outstandingEnabled, outstandingRule, dataField]);
+
+    /** Stored ids the field no longer offers — drives the amber warning. */
+    const outstandingStaleIds = useMemo(
+        () => (outstandingEnabled ? staleOutstandingIds(dataField) : []),
+        [outstandingEnabled, dataField]
+    );
+
     // Generate compact field info for display in the center top
     const getFieldInfo = (field) => {
         const fieldTypeLabel =
@@ -182,6 +331,14 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             info.push('Conditional');
         }
 
+        // Only surfaced for apps that opted into outstanding-item rules.
+        if (outstandingItems?.enabled) {
+            const outstandingSummary = summariseOutstandingRule(field);
+            if (outstandingSummary) {
+                info.push(outstandingSummary);
+            }
+        }
+
         return info.join(' • ');
     };
 
@@ -229,6 +386,13 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             tooltip += `Show when "${field.conditional_field}" = "${field.conditional_value}"\n`;
         }
 
+        if (outstandingItems?.enabled) {
+            const outstandingSummary = summariseOutstandingRule(field);
+            if (outstandingSummary) {
+                tooltip += `\nOutstanding rule: ${outstandingSummary}\n`;
+            }
+        }
+
         // Add other conditional properties if they exist
         if (field.conditionalOperator) {
             tooltip += `Operator: ${field.conditionalOperator}\n`;
@@ -1027,7 +1191,11 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             textareaHeight: 'normal',
             conditional_field: '',
             conditional_value: '',
+            // `outstanding_when` is deliberately NOT seeded here: absent must
+            // stay absent so a field that was never configured never gains the
+            // key just by being opened.
         }));
+        setOutstandingRule({ touched: false, id: null });
         setModalType(() => ({
             type: 'create',
             key: '',
@@ -1047,10 +1215,28 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             const { name, value } = e.target;
             const updatedValue = name === 'id' ? slugify(value) : value;
 
-            setDataField((items) => ({
-                ...items,
-                [name]: updatedValue,
-            }));
+            setDataField((items) => {
+                const next = { ...items, [name]: updatedValue };
+
+                // Switching to a type that cannot carry an outstanding rule
+                // would strand the key with no UI left to edit it.
+                if (
+                    name === 'type' &&
+                    'outstanding_when' in next &&
+                    !isOutstandingConfigurable(outstandingItems, updatedValue)
+                ) {
+                    delete next.outstanding_when;
+                }
+
+                return next;
+            });
+
+            if (
+                name === 'type' &&
+                !isOutstandingConfigurable(outstandingItems, updatedValue)
+            ) {
+                setOutstandingRule({ touched: false, id: null });
+            }
 
             if (name === 'label') {
                 setDataField((items) => ({
@@ -1080,6 +1266,10 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                 ...detail[key],
             }));
 
+            // Untouched: the switch shows whatever the stored rule — or the
+            // standard rule — implies, recomputed as the author edits.
+            setOutstandingRule({ touched: false, id: null });
+
             setModalType(() => ({
                 type: 'update',
                 key: key,
@@ -1158,6 +1348,11 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
 
         field.id = formatFieldId(field.id);
 
+        // No-op unless the consuming app enabled outstanding-item rules. Writes
+        // `outstanding_when` only when the switch differs from the standard
+        // rule, so opening and saving an untouched field changes nothing.
+        field = applyOutstandingRule(field, outstandingSelection, outstandingItems);
+
         let errorMessage = validateField(field);
 
         if (errorMessage === '') {
@@ -1598,6 +1793,49 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
         }
     };
 
+    /**
+     * Re-anchor the collision guard on the version just written.
+     *
+     * Called after a save rather than after a re-fetch: the payload that was
+     * accepted IS what the row now holds, and asking the server again would
+     * cost a round trip to learn something already known.
+     */
+    const rememberDetailHash = async (templateId, detail) => {
+        if (!lockEnabled) {
+            return;
+        }
+
+        expectedDetailHashRef.current = await detailContentHash(
+            templateId,
+            detail,
+            lockSchemaVersion
+        );
+    };
+
+    /**
+     * "Somebody else got here first", in the only words that help.
+     *
+     * No silent retry, ever. A retry would re-send this tab's whole `detail`
+     * over the top of whatever arrived in the meantime, which is precisely the
+     * overwrite the guard exists to prevent.
+     */
+    const handleStaleTemplate = (payload) => {
+        const versions =
+            payload?.expected_version && payload?.current_version
+                ? ` (you have ${payload.expected_version}, the system now has ${payload.current_version})`
+                : '';
+
+        toast.error(
+            <div>
+                <strong>Nothing was saved.</strong> This template was changed
+                elsewhere — imported from a spreadsheet, or edited in another
+                tab — after you opened it{versions}. Reload the page before
+                saving, or your changes would undo theirs.
+            </div>,
+            { autoClose: false }
+        );
+    };
+
     const handleSubmit = async (e) => {
         try {
             if (e) {
@@ -1610,15 +1848,34 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                 }
 
                 if (_error === '') {
+                    const savedDetail = data.detail;
+
+                    // The guard answers a 409 in its own words, so the shared
+                    // handler's toast is suppressed and replayed in the catch
+                    // for every other failure — same message, same behaviour,
+                    // just deferred until the status is known.
                     const res = await CustomFetch(
                         `${fetchUrl}/${dataId}`,
                         'PUT',
                         {
                             ...data,
-                        }
+                            // Only when the backend understands it, and only
+                            // when a hash could actually be computed. Absent,
+                            // the server saves exactly as it always has.
+                            ...(lockEnabled && expectedDetailHashRef.current
+                                ? {
+                                      expected_detail_hash:
+                                          expectedDetailHashRef.current,
+                                  }
+                                : {}),
+                        },
+                        null,
+                        lockEnabled ? () => {} : null
                     );
 
                     if (res.data.error === '') {
+                        await rememberDetailHash(data.id, savedDetail);
+
                         toast.success(
                             "You have successfully updated the form's detail."
                         );
@@ -1632,6 +1889,32 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                 }
             }
         } catch (err) {
+            if (err?.response?.status === 409) {
+                handleStaleTemplate(err.response.data);
+
+                return;
+            }
+
+            if (lockEnabled) {
+                // Replay what the shared handler would have said, in the same
+                // order it would have said it — field errors before the
+                // envelope's generic message.
+                const payload = err?.response?.data;
+                const message = payload?.errors
+                    ? Object.values(payload.errors).flat().join('<br />')
+                    : payload?.message || null;
+
+                if (message && message !== 'Unauthenticated.') {
+                    toast.error(<div>{parse(String(message))}</div>);
+
+                    return;
+                }
+
+                if (err?.response) {
+                    return;
+                }
+            }
+
             toast.error(`Error: ${err}`);
         }
     };
@@ -1645,6 +1928,10 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
             );
 
             setData(res.data);
+
+            // The version this tab is editing from. Everything the guard does
+            // is measured against this moment.
+            await rememberDetailHash(res.data?.id, res.data?.detail);
         } catch (err) {
             toast.error(`Error: ${err}`);
         }
@@ -1652,17 +1939,26 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
 
     const saveOnSort = async () => {
         try {
+            const savedDetail = data.detail;
             const res = await CustomFetch(
                 `${fetchUrl}/sort/${dataId}`,
                 'POST',
                 {
-                    detail: data.detail,
+                    detail: savedDetail,
                 }
             );
 
             if (res.data.error !== '') {
                 toast.error(String(res.data.error));
+
+                return;
             }
+
+            // Re-ordering writes `detail` too, so the guard has to follow it.
+            // The sort endpoint reads only `detail` and cannot be guarded from
+            // here — but leaving the hash behind would make the next Save
+            // report a collision this tab caused itself.
+            await rememberDetailHash(data.id, savedDetail);
         } catch (err) {
             toast.error(`Error: ${err}`);
         }
@@ -2378,6 +2674,14 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                                                     </span>
                                                 )}
                                             </div>
+                                            {outstandingEnabled ? (
+                                                <OutstandingRuleHint
+                                                    config={outstandingItems}
+                                                    staleIds={
+                                                        outstandingStaleIds
+                                                    }
+                                                />
+                                            ) : null}
                                             {dataField.options.length >
                                             0 ? (
                                                 <div
@@ -2415,6 +2719,15 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                                                                     onChange={(
                                                                         e
                                                                     ) => {
+                                                                        // Captured before the id is regenerated so any
+                                                                        // outstanding rule pointing at it can follow.
+                                                                        const previousOptionId =
+                                                                            dataField
+                                                                                .options[
+                                                                                optionKey
+                                                                            ]
+                                                                                ?.id;
+                                                                        const nextOptionId = `${slugify(e.target.value)}-`;
                                                                         const newOptions =
                                                                             [
                                                                                 ...dataField.options,
@@ -2426,18 +2739,65 @@ function GenericFormBuilder({ setting, urlParam, userProfile }) {
                                                                         newOptions[
                                                                             optionKey
                                                                         ].id =
-                                                                            `${slugify(e.target.value)}-`;
+                                                                            nextOptionId;
                                                                         setDataField(
                                                                             (
                                                                                 items
-                                                                            ) => ({
-                                                                                ...items,
-                                                                                options:
-                                                                                    newOptions,
-                                                                            })
+                                                                            ) =>
+                                                                                remapOutstandingWhen(
+                                                                                    {
+                                                                                        ...items,
+                                                                                        options:
+                                                                                            newOptions,
+                                                                                    },
+                                                                                    previousOptionId,
+                                                                                    nextOptionId
+                                                                                )
+                                                                        );
+
+                                                                        // An unsaved switch has to follow the
+                                                                        // rename too, or it would be sanitised
+                                                                        // away as a dangling id.
+                                                                        setOutstandingRule(
+                                                                            (
+                                                                                rule
+                                                                            ) =>
+                                                                                rule.touched &&
+                                                                                rule.id ===
+                                                                                    previousOptionId
+                                                                                    ? {
+                                                                                          ...rule,
+                                                                                          id: nextOptionId,
+                                                                                      }
+                                                                                    : rule
                                                                         );
                                                                     }}
                                                                 />
+                                                                {outstandingEnabled ? (
+                                                                    <OutstandingOptionToggle
+                                                                        optionId={
+                                                                            option.id
+                                                                        }
+                                                                        label={
+                                                                            option.label ||
+                                                                            option.id
+                                                                        }
+                                                                        checked={
+                                                                            outstandingSelection ===
+                                                                            option.id
+                                                                        }
+                                                                        onToggle={(
+                                                                            id
+                                                                        ) =>
+                                                                            setOutstandingRule(
+                                                                                {
+                                                                                    touched: true,
+                                                                                    id,
+                                                                                }
+                                                                            )
+                                                                        }
+                                                                    />
+                                                                ) : null}
                                                                 <button
                                                                     className={
                                                                         styles.optionDelete