@visns-studio/visns-components 6.3.5 → 6.3.7

package/package.json

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

package/src/components/DataGrid.jsx

@@ -78,6 +78,16 @@ import {
 } from 'lucide-react';
 import styles from './styles/DataGrid.module.scss';
 
+/**
+ * `ajaxSetting.rowStyles[].style` tokens → the module class that draws them.
+ * Kept as a map rather than `styles['row' + capitalise(token)]` so an unknown
+ * token in a config is simply ignored instead of resolving to `undefined` and
+ * putting the literal string "undefined" in the row's class list.
+ */
+const ROW_STYLE_CLASSES = {
+    complete: styles.rowComplete,
+};
+
 import '@visns-studio/visns-datagrid-enterprise/index.css';
 
 import CustomFetch from './Fetch';
@@ -959,6 +969,80 @@ const DataGrid = forwardRef(
             [ajaxSetting]
         );
 
+        /**
+         * Opt-in non-colour row states (`ajaxSetting.rowStyles`).
+         *
+         *   rowStyles: [
+         *       { id: 'jigging_status', value: 1, style: 'complete' }
+         *   ]
+         *
+         * Each rule names a FIELD STATE, not a look: `style` is a token the
+         * package maps to a class in DataGrid.module.scss, so a project says
+         * what a row means and the library decides how that reads. Today the
+         * only token is `complete` (line-through plus a muted ink).
+         *
+         * Deliberately different from `rowColours` in two ways:
+         *
+         *  - EVERY matching rule applies, where rowColours takes the first
+         *    match only. A row is frequently more than one thing at once (a
+         *    finished item that is also on a T-Bar), and with first-match the
+         *    completion state would be swallowed by whichever tint happened to
+         *    be listed above it.
+         *  - It carries no colour. That is the point: a pale tint is the first
+         *    thing to disappear on a plant-floor tablet in daylight, so a state
+         *    that matters has to be legible without one. Colour, where a rule
+         *    also sets one, stays the redundant second channel.
+         *
+         * `operator` follows the same small vocabulary as `readOnlyWhen`:
+         * eq (default), neq, notEmpty.
+         */
+        const getRowClassName = useCallback(
+            ({ data }) => {
+                const rules = ajaxSetting?.rowStyles;
+
+                if (!Array.isArray(rules) || rules.length === 0 || !data) {
+                    return '';
+                }
+
+                const matches = (rule) => {
+                    const value = data[rule.id];
+
+                    switch (rule.operator) {
+                        case 'neq':
+                            return value != rule.value;
+                        case 'notEmpty':
+                            return Array.isArray(value)
+                                ? value.length > 0
+                                : value != null && value !== '';
+                        case 'eq':
+                        default:
+                            return value == rule.value;
+                    }
+                };
+
+                return rules
+                    .filter(matches)
+                    .map((rule) => ROW_STYLE_CLASSES[rule.style])
+                    .filter(Boolean)
+                    .join(' ');
+            },
+            [ajaxSetting]
+        );
+
+        /**
+         * The grid's own row class plus whatever `rowStyles` adds. Passed as a
+         * function rather than the bare string the grid used to get: the grid
+         * accepts either, and `vs-datagrid--row` (the hover rule) has to stay
+         * on every row regardless.
+         */
+        const rowClassName = useCallback(
+            (rowProps) =>
+                ['vs-datagrid--row', getRowClassName(rowProps)]
+                    .filter(Boolean)
+                    .join(' '),
+            [getRowClassName]
+        );
+
         const handleDownload = async (d) => {
             const toastId = toast.loading('Starting download please wait...');
 
@@ -5205,7 +5289,7 @@ const DataGrid = forwardRef(
                             pagination
                             renderRowContextMenu={renderRowContextMenu}
                             renderColumnContextMenu={renderColumnContextMenu}
-                            rowClassName="vs-datagrid--row"
+                            rowClassName={rowClassName}
                             rowHeight={isTabletMode ? 52 : null}
                             rowStyle={getRowStyle}
                             selected={selected}

package/src/components/Field.jsx

@@ -139,6 +139,11 @@ function Field({
     onDeleteJsonTableRow,
     onChangeToggle,
     onFileDownload,
+    // Renders another of the form's fields inside this one (today: inside a
+    // `multi-checkbox-ajax` option card, via `settings.optionFields`).
+    // Supplied by Form so the nested field keeps the form's own state,
+    // handlers and validation — see Form.renderCompanionField.
+    renderOptionField,
     setFormData,
     settings,
     style,
@@ -1161,6 +1166,13 @@ function Field({
                         onValueChange={(values) => {
                             onChangeNumberFormat(values, settings.id);
                         }}
+                        // Numeric inputs ignored both of these: a
+                        // `placeholder` in the config never rendered, and a
+                        // read-only field stayed typable. The placeholder is
+                        // also how a `sumEquals` group offers its remainder
+                        // as a hint (see SumEqualsSummary).
+                        placeholder={settings.placeholder}
+                        disabled={isFieldReadOnly}
                         thousandSeparator={
                             settings.hasOwnProperty('thousandSeperator')
                                 ? settings.thousandSeperator
@@ -2187,6 +2199,16 @@ function Field({
                         // claiming a lock the UI didn't enforce — the same gap
                         // the radio renderers had.
                         disabled={isFieldReadOnly}
+                        optionFields={settings.optionFields}
+                        // A read-only host locks the fields in its cards too
+                        renderOptionField={
+                            renderOptionField
+                                ? (fieldId) =>
+                                      renderOptionField(fieldId, {
+                                          readOnly: isFieldReadOnly,
+                                      })
+                                : undefined
+                        }
                         style={style}
                     />
                 );

package/src/components/Form.jsx

@@ -18,6 +18,10 @@ import '@visns-studio/visns-datagrid-enterprise/index.css';
 import CustomFetch from './Fetch';
 import Download from './Download';
 import Field from './Field';
+import SumEqualsSummary, {
+    computeSumEqualsState,
+    sumEqualsHintFor,
+} from './SumEqualsSummary';
 import Table from './DataGrid';
 
 import styles from './styles/Form.module.scss';
@@ -1428,58 +1432,57 @@ function Form({
                          * ordinary save. While visible it also stands in for
                          * `required` on the whole group: a blank member is as
                          * wrong as a wrong total.
+                         *
+                         * Declaring the rule also turns on live feedback
+                         * while the operator types, all of it automatic —
+                         * no extra config, and nothing a form has to opt
+                         * into beyond `sumEquals` itself:
+                         *
+                         *  - an allocation line under the group, reading
+                         *    "Item Qty 40 · 25 entered · 15 remaining",
+                         *    "40 of 40 allocated ✓" or "over by 5" (see
+                         *    SumEqualsSummary);
+                         *  - the remainder offered as the placeholder of the
+                         *    group's one empty field — a hint only, never an
+                         *    auto-filled value.
+                         *
+                         * `targetLabel` on the rule names the total in that
+                         * copy; it otherwise takes the label of the field
+                         * `equals` points at.
                          */
                         if (item.sumEquals && item.hide !== true) {
                             const rule = item.sumEquals;
-                            const groupIds = Array.isArray(rule.fields)
-                                ? rule.fields
-                                : [];
+                            // Same computation the live summary and the
+                            // placeholder hint use, so what the operator was
+                            // told while typing is exactly what is enforced
+                            const state = computeSumEqualsState(rule, formData);
 
-                            if (groupIds.length > 0) {
+                            if (state) {
                                 const labelFor = (fieldId) =>
                                     fields.find((f) => f.id === fieldId)
                                         ?.label || fieldId;
-                                const groupLabels = groupIds
+                                const groupLabels = state.ids
                                     .map(labelFor)
                                     .join(' and ');
-                                const groupValues = groupIds.map(
-                                    (fieldId) => formData[fieldId]
-                                );
-                                const incomplete = groupValues.some(
-                                    (v) =>
-                                        v === null ||
-                                        v === undefined ||
-                                        v === '' ||
-                                        isNaN(Number(v))
-                                );
-
-                                const target =
-                                    typeof rule.equals === 'number'
-                                        ? rule.equals
-                                        : Number(formData[rule.equals]);
 
                                 const markGroup = () =>
-                                    groupIds.forEach((fieldId) => {
+                                    state.ids.forEach((fieldId) => {
                                         _inputClass[fieldId] =
                                             styles.inputError;
                                     });
 
-                                if (incomplete) {
+                                if (state.emptyIds.length > 0) {
                                     validation += `${groupLabels} are required.<br/>`;
                                     markGroup();
-                                } else if (!isNaN(target)) {
-                                    const sum = groupValues.reduce(
-                                        (total, v) => total + Number(v),
-                                        0
-                                    );
-
-                                    if (sum !== target) {
-                                        validation +=
-                                            (rule.message ||
-                                                `${groupLabels} must add up to ${target} - they add up to ${sum}.`) +
-                                            '<br/>';
-                                        markGroup();
-                                    }
+                                } else if (
+                                    state.hasTarget &&
+                                    state.status !== 'balanced'
+                                ) {
+                                    validation +=
+                                        (rule.message ||
+                                            `${groupLabels} must add up to ${state.target} - they add up to ${state.sum}.`) +
+                                        '<br/>';
+                                    markGroup();
                                 }
                             }
                         }
@@ -2899,6 +2902,193 @@ function Form({
         });
     }, [fetchTrigger]);
 
+    /**
+     * The `sumEquals` rule a field belongs to, wherever it was declared (the
+     * rule sits on one member and names the whole group).
+     */
+    const sumEqualsRuleFor = (fieldId) =>
+        formSettings?.fields?.find(
+            (f) =>
+                f.sumEquals &&
+                Array.isArray(f.sumEquals.fields) &&
+                f.sumEquals.fields.includes(fieldId)
+        )?.sumEquals || null;
+
+    /**
+     * Field ids a `multi-checkbox-ajax` host has claimed through
+     * `optionFields`: those render inside the option cards, not as rows of
+     * their own, so the main loop must skip them.
+     */
+    const optionHostedFieldIds = new Set(
+        (formSettings?.fields || []).flatMap((f) =>
+            Array.isArray(f.optionFields) ? f.optionFields : []
+        )
+    );
+
+    /**
+     * The field the group's allocation line renders under: the last member
+     * that the main loop draws itself, or — when every member is nested in an
+     * option card — the host that draws them.
+     */
+    const sumEqualsAnchorId = (rule) => {
+        const ids = Array.isArray(rule?.fields) ? rule.fields : [];
+        const ownRows = ids.filter((id) => !optionHostedFieldIds.has(id));
+
+        if (ownRows.length > 0) {
+            return ownRows[ownRows.length - 1];
+        }
+
+        return (
+            (formSettings?.fields || []).find(
+                (f) =>
+                    Array.isArray(f.optionFields) &&
+                    ids.some((id) => f.optionFields.includes(id))
+            )?.id || null
+        );
+    };
+
+    /**
+     * The allocation line to draw after `item`, or null. Rendered once per
+     * group, under the group's last field (or under the checkbox host whose
+     * cards contain them), and never while that anchor is hidden.
+     */
+    const renderSumEqualsSummary = (item) => {
+        const rules = (formSettings?.fields || [])
+            .map((f) => f.sumEquals)
+            .filter(Boolean)
+            .filter((rule) => sumEqualsAnchorId(rule) === item.id);
+
+        if (rules.length === 0) {
+            return null;
+        }
+
+        return rules.map((rule, i) => {
+            // A group whose fields are all hidden says nothing: the section
+            // it belongs to has not been revealed yet
+            const anyVisible = (rule.fields || []).some(
+                (id) =>
+                    formSettings.fields.find((f) => f.id === id)?.hide !== true
+            );
+
+            if (!anyVisible) {
+                return null;
+            }
+
+            return (
+                <SumEqualsSummary
+                    key={`${item.id}-sumequals-${i}`}
+                    rule={rule}
+                    formData={formData}
+                    fields={formSettings.fields}
+                />
+            );
+        });
+    };
+
+    /**
+     * `item`, with the remainder offered as its placeholder when it is the
+     * one field of its `sumEquals` group still empty. Returns the original
+     * object when there is nothing to add, so React sees no new prop.
+     */
+    const withSumEqualsHint = (item) => {
+        const rule = sumEqualsRuleFor(item.id);
+
+        if (!rule) {
+            return item;
+        }
+
+        const hint = sumEqualsHintFor(item.id, rule, formData);
+
+        if (hint === undefined) {
+            return item;
+        }
+
+        return { ...item, placeholder: hint };
+    };
+
+    /**
+     * One `<Field>`, wired to this form's state and handlers. Single factory
+     * so a field rendered inside an option card (see renderCompanionField)
+     * is wired identically to one rendered on a row of its own.
+     */
+    const renderFormField = (item, key) => (
+        <Field
+            api={api}
+            autocompleteCallback={autocompleteSelect}
+            childDropdownCallback={childDropdownCallback}
+            fetchData={fetchData}
+            formData={formData}
+            formSettings={formSettings}
+            inputClass={inputClass}
+            inputValue={renderInputValue(item, formData)}
+            key={key}
+            mapbox={mapbox}
+            onChange={handleChange}
+            onChangeCanvas={handleChangeCanvas}
+            onChangeCheckbox={handleChangeCheckbox}
+            onChangeCheckboxManual={handleChangeCheckboxManual}
+            onChangeColour={handleChangeColour}
+            onChangeDate={handleChangeDate}
+            onChangeNumberFormat={handleChangeNumberFormat}
+            onChangeRicheditor={handleChangeRicheditor}
+            onChangeSignature={handleChangeSignature}
+            onChangeSelect={handleChangeSelect}
+            onChangeToggle={handleChangeToggle}
+            onChangeJsonTable={handleChangeJsonTable}
+            onAddJsonTableRow={handleAddJsonTableRow}
+            onDeleteJsonTableRow={handleDeleteJsonTableRow}
+            onFileDownload={handleFileDownload}
+            renderOptionField={renderCompanionField}
+            settings={item}
+            setFormData={setFormData}
+            style={style}
+            uploadProgress={uploadProgress}
+            userProfile={userProfile}
+        />
+    );
+
+    /**
+     * Render one of this form's fields somewhere other than its own row —
+     * today, inside a `multi-checkbox-ajax` option card (see `optionFields`
+     * in MultiCheckbox). It is the SAME field: same id, same formData entry,
+     * same handlers, same validation and same `sumEquals` membership. Only
+     * the mount point differs, so there is no second source of truth.
+     *
+     * @param {string} fieldId
+     * @param {{readOnly?: boolean}} options host state to inherit
+     */
+    const renderCompanionField = (fieldId, options = {}) => {
+        const field = formSettings?.fields?.find((f) => f.id === fieldId);
+
+        // A field the `show` rules have not revealed stays hidden wherever it
+        // is mounted — ticking one box must not surface the qty inputs
+        if (!field || field.hide === true) {
+            return null;
+        }
+
+        const settings = {
+            ...withSumEqualsHint(field),
+            // The card is the field's context ("Station A"), so the label
+            // inside it can be short. The full label stays the group's
+            // accessible name below.
+            label: field.compactLabel || field.label,
+            // Companion fields fill their card, whatever width they were
+            // given for a row of their own
+            size: 'full',
+            // A read-only host locks what it contains
+            readOnly: field.readOnly === true || options.readOnly === true,
+            // Cards do not nest: a companion never hosts companions of
+            // its own
+            optionFields: undefined,
+        };
+
+        return (
+            <div role="group" aria-label={field.label}>
+                {renderFormField(settings, `companion-${fieldId}`)}
+            </div>
+        );
+    };
+
     if (type && type === 'inline') {
         return (
             <div className={styles.formcontainer}>
@@ -2957,67 +3147,36 @@ function Form({
                                         />
                                     </div>
                                 );
-                            default:
-                                return (
-                                    <Field
-                                        api={api}
-                                        autocompleteCallback={
-                                            autocompleteSelect
-                                        }
-                                        childDropdownCallback={
-                                            childDropdownCallback
-                                        }
-                                        fetchData={fetchData}
-                                        formData={formData}
-                                        formSettings={formSettings}
-                                        inputClass={inputClass}
-                                        inputValue={renderInputValue(
-                                            item,
-                                            formData
+                            default: {
+                                // Drawn inside a checkbox option card
+                                // instead of on a row of its own
+                                if (optionHostedFieldIds.has(item.id)) {
+                                    return null;
+                                }
+
+                                const key =
+                                    index +
+                                    '-fields-' +
+                                    (item.hasOwnProperty('key')
+                                        ? item.id + '-' + item.key
+                                        : item.id);
+                                const summary = renderSumEqualsSummary(item);
+
+                                return summary ? (
+                                    <React.Fragment key={`${key}-group`}>
+                                        {renderFormField(
+                                            withSumEqualsHint(item),
+                                            key
                                         )}
-                                        key={
-                                            index +
-                                            '-fields-' +
-                                            (item.hasOwnProperty('key')
-                                                ? item.id + '-' + item.key
-                                                : item.id)
-                                        }
-                                        mapbox={mapbox}
-                                        onChange={handleChange}
-                                        onChangeCanvas={handleChangeCanvas}
-                                        onChangeCheckbox={handleChangeCheckbox}
-                                        onChangeCheckboxManual={
-                                            handleChangeCheckboxManual
-                                        }
-                                        onChangeDate={handleChangeDate}
-                                        onChangeNumberFormat={
-                                            handleChangeNumberFormat
-                                        }
-                                        onChangeRicheditor={
-                                            handleChangeRicheditor
-                                        }
-                                        onChangeSelect={handleChangeSelect}
-                                        onChangeSignature={
-                                            handleChangeSignature
-                                        }
-                                        onChangeToggle={handleChangeToggle}
-                                        onChangeJsonTable={
-                                            handleChangeJsonTable
-                                        }
-                                        onAddJsonTableRow={
-                                            handleAddJsonTableRow
-                                        }
-                                        onDeleteJsonTableRow={
-                                            handleDeleteJsonTableRow
-                                        }
-                                        onFileDownload={handleFileDownload}
-                                        settings={item}
-                                        setFormData={setFormData}
-                                        style={style}
-                                        uploadProgress={uploadProgress}
-                                        userProfile={userProfile}
-                                    />
+                                        {summary}
+                                    </React.Fragment>
+                                ) : (
+                                    renderFormField(
+                                        withSumEqualsHint(item),
+                                        key
+                                    )
                                 );
+                            }
                         }
                     })}
                     <div className={`${styles.formItem} ${styles.fwItem}`}>
@@ -3627,68 +3786,34 @@ function Form({
                                         return null;
                                     }
 
-                                    return (
-                                        <Field
-                                            api={api}
-                                            autocompleteCallback={
-                                                autocompleteSelect
-                                            }
-                                            childDropdownCallback={
-                                                childDropdownCallback
-                                            }
-                                            fetchData={fetchData}
-                                            formData={formData}
-                                            formSettings={formSettings}
-                                            inputClass={inputClass}
-                                            inputValue={renderInputValue(
-                                                item,
-                                                formData
+                                    // Drawn inside a checkbox option card
+                                    // instead of on a row of its own
+                                    if (optionHostedFieldIds.has(item.id)) {
+                                        return null;
+                                    }
+
+                                    const key =
+                                        index +
+                                        '-fields-' +
+                                        (item.hasOwnProperty('key')
+                                            ? item.id + '-' + item.key
+                                            : item.id);
+                                    const summary =
+                                        renderSumEqualsSummary(item);
+
+                                    return summary ? (
+                                        <React.Fragment key={`${key}-group`}>
+                                            {renderFormField(
+                                                withSumEqualsHint(item),
+                                                key
                                             )}
-                                            key={
-                                                index +
-                                                '-fields-' +
-                                                (item.hasOwnProperty('key')
-                                                    ? item.id + '-' + item.key
-                                                    : item.id)
-                                            }
-                                            mapbox={mapbox}
-                                            onChange={handleChange}
-                                            onChangeCanvas={handleChangeCanvas}
-                                            onChangeCheckbox={
-                                                handleChangeCheckbox
-                                            }
-                                            onChangeCheckboxManual={
-                                                handleChangeCheckboxManual
-                                            }
-                                            onChangeColour={handleChangeColour}
-                                            onChangeDate={handleChangeDate}
-                                            onChangeNumberFormat={
-                                                handleChangeNumberFormat
-                                            }
-                                            onChangeRicheditor={
-                                                handleChangeRicheditor
-                                            }
-                                            onChangeSignature={
-                                                handleChangeSignature
-                                            }
-                                            onChangeSelect={handleChangeSelect}
-                                            onChangeToggle={handleChangeToggle}
-                                            onChangeJsonTable={
-                                                handleChangeJsonTable
-                                            }
-                                            onAddJsonTableRow={
-                                                handleAddJsonTableRow
-                                            }
-                                            onDeleteJsonTableRow={
-                                                handleDeleteJsonTableRow
-                                            }
-                                            onFileDownload={handleFileDownload}
-                                            settings={item}
-                                            setFormData={setFormData}
-                                            style={style}
-                                            uploadProgress={uploadProgress}
-                                            userProfile={userProfile}
-                                        />
+                                            {summary}
+                                        </React.Fragment>
+                                    ) : (
+                                        renderFormField(
+                                            withSumEqualsHint(item),
+                                            key
+                                        )
                                     );
                                 })}
                                 <div

package/src/components/MultiCheckbox.jsx

@@ -21,6 +21,26 @@ function MultiCheckbox({
     // gap the radio renderers had). Disabling the boxes also takes the
     // create/edit affordances away — they mutate the option list.
     disabled = false,
+    /**
+     * Companion form fields to draw INSIDE the option cards, so each option
+     * reads as one self-contained unit ("Station A [✓] Qty 25") rather than a
+     * detached row of inputs below the group.
+     *
+     *     optionFields: ['split_station_qty_1', 'split_station_qty_2']
+     *
+     * Positional against the SELECTED options **in the order the options are
+     * rendered**, not the order they were clicked — so the mapping is stable
+     * however the operator ticks the boxes, and lines up with a backend
+     * reading the same list in the same order.
+     *
+     * The fields are the form's own: `renderOptionField(fieldId)` mounts the
+     * real field (same id, same value, same validation, same sumEquals
+     * membership), so there is no second source of truth. It returns null for
+     * a field the form's `show` rules have not revealed — which is what keeps
+     * the quantity inputs hidden until a second box is ticked.
+     */
+    optionFields = [],
+    renderOptionField,
 }) {
     const [checkboxOptions, setCheckboxOptions] = useState([]);
     const [selectedValues, setSelectedValues] = useState([]);
@@ -191,6 +211,28 @@ function MultiCheckbox({
 
     const maxColumns = settings.maxColumns || 3;
 
+    /**
+     * The companion field id for an option: its position among the SELECTED
+     * options, counted in render order (see the `optionFields` docs above).
+     * Null when the option is unselected, unmapped, or nothing was supplied
+     * to render it with.
+     */
+    const selectedInRenderOrder = filteredOptions.filter((option) =>
+        isSelected(option.id)
+    );
+
+    const optionFieldIdFor = (option) => {
+        if (!renderOptionField || optionFields.length === 0) {
+            return null;
+        }
+
+        const position = selectedInRenderOrder.findIndex(
+            (selected) => String(selected.id) === String(option.id)
+        );
+
+        return position >= 0 ? optionFields[position] ?? null : null;
+    };
+
     return (
         <div className={`${styles.multiCheckbox} ${className || ''}`} style={style}>
 
@@ -257,8 +299,19 @@ function MultiCheckbox({
                     gridTemplateColumns: `repeat(${maxColumns}, 1fr)`
                 }}
             >
-                {filteredOptions.map((option, index) => (
-                    <div key={option.id || `option-${index}`} className={styles.checkboxItem}>
+                {filteredOptions.map((option, index) => {
+                    const optionFieldId = optionFieldIdFor(option);
+                    const optionField = optionFieldId
+                        ? renderOptionField(optionFieldId, option)
+                        : null;
+
+                    return (
+                    <div
+                        key={option.id || `option-${index}`}
+                        className={`${styles.checkboxItem} ${
+                            optionField ? styles.hasOptionField : ''
+                        }`}
+                    >
                         {isEditing === option.id ? (
                             <div className={styles.editForm}>
                                 <input
@@ -322,8 +375,21 @@ function MultiCheckbox({
                                 )}
                             </label>
                         )}
+                        {/*
+                          * Outside the <label> on purpose: an input nested in
+                          * a label toggles that label's checkbox, so typing a
+                          * quantity would untick the station it belongs to.
+                          * Sitting here also gives the natural tab order —
+                          * checkbox, its own quantity, then the next card.
+                          */}
+                        {optionField && (
+                            <div className={styles.optionField}>
+                                {optionField}
+                            </div>
+                        )}
                     </div>
-                ))}
+                    );
+                })}
             </div>
 
             {/* No options message */}

package/src/components/SumEqualsSummary.jsx

@@ -0,0 +1,147 @@
+import React from 'react';
+import styles from './styles/SumEqualsSummary.module.scss';
+
+/**
+ * Live feedback for a `sumEquals` field group — see the rule's documentation
+ * in Form.jsx.
+ *
+ * The rule declares a set of numeric fields that must add up to a target:
+ *
+ *     sumEquals: { fields: ['qty_a', 'qty_b'], equals: 'qty_total' }
+ *
+ * At submit time Form validates it. Everything here is the progressive half:
+ * while the operator types, the group says what the target is, how much is
+ * already allocated and how much is left, and the one empty field offers the
+ * remainder as a placeholder. None of it replaces the validation — a form
+ * that never renders the summary still refuses a wrong total.
+ */
+
+const isBlank = (value) =>
+    value === null ||
+    value === undefined ||
+    value === '' ||
+    isNaN(Number(value));
+
+/**
+ * The group's running state, or null when the rule names no fields.
+ *
+ * @param {object} rule      the field's `sumEquals` declaration
+ * @param {object} formData  current form values
+ * @returns {{
+ *   ids: string[], target: number, hasTarget: boolean, sum: number,
+ *   remaining: number|null, entered: number, emptyIds: string[],
+ *   status: 'under'|'balanced'|'over'|'unknown'
+ * }|null}
+ */
+export const computeSumEqualsState = (rule, formData = {}) => {
+    const ids = Array.isArray(rule?.fields) ? rule.fields : [];
+
+    if (ids.length === 0) {
+        return null;
+    }
+
+    const target =
+        typeof rule.equals === 'number'
+            ? rule.equals
+            : Number(formData[rule.equals]);
+    const hasTarget = !isNaN(target);
+
+    const emptyIds = ids.filter((id) => isBlank(formData[id]));
+    const sum = ids.reduce(
+        (total, id) => (isBlank(formData[id]) ? total : total + Number(formData[id])),
+        0
+    );
+    const remaining = hasTarget ? target - sum : null;
+
+    return {
+        ids,
+        target,
+        hasTarget,
+        sum,
+        remaining,
+        entered: ids.length - emptyIds.length,
+        emptyIds,
+        status: !hasTarget
+            ? 'unknown'
+            : remaining > 0
+            ? 'under'
+            : remaining < 0
+            ? 'over'
+            : 'balanced',
+    };
+};
+
+/**
+ * The remainder to offer as `fieldId`'s placeholder, or undefined.
+ *
+ * Only when that field is the ONLY empty one in its group and something is
+ * actually left to allocate — a placeholder on two empty fields would be a
+ * guess, and one showing "0" or a negative would be wrong. Deliberately a
+ * placeholder and never a value: the operator types the number themselves.
+ */
+export const sumEqualsHintFor = (fieldId, rule, formData = {}) => {
+    const state = computeSumEqualsState(rule, formData);
+
+    if (
+        !state ||
+        !state.hasTarget ||
+        state.emptyIds.length !== 1 ||
+        state.emptyIds[0] !== fieldId ||
+        state.remaining <= 0
+    ) {
+        return undefined;
+    }
+
+    return String(state.remaining);
+};
+
+/**
+ * One line under a `sumEquals` group:
+ *
+ *   under      "Item Qty 40 · 25 entered · 15 remaining"   (muted)
+ *   balanced   "40 of 40 allocated ✓"                      (success)
+ *   over       "Item Qty 40 · 45 entered · over by 5"      (error)
+ *
+ * The height is reserved in CSS so moving between the three never shifts the
+ * form. `targetLabel` names the total in the copy: the rule's own
+ * `targetLabel`, else the label of the field `equals` points at, else
+ * "Total".
+ */
+const SumEqualsSummary = ({ rule, formData, fields = [] }) => {
+    const state = computeSumEqualsState(rule, formData);
+
+    if (!state) {
+        return null;
+    }
+
+    const targetLabel =
+        rule.targetLabel ||
+        fields.find((f) => f.id === rule.equals)?.label ||
+        'Total';
+
+    let text = ' ';
+    let tone = styles.neutral;
+
+    if (state.hasTarget) {
+        if (state.status === 'balanced') {
+            text = `${state.sum} of ${state.target} allocated ✓`;
+            tone = styles.balanced;
+        } else if (state.status === 'over') {
+            text = `${targetLabel} ${state.target} · ${state.sum} entered · over by ${Math.abs(
+                state.remaining
+            )}`;
+            tone = styles.over;
+        } else {
+            text = `${targetLabel} ${state.target} · ${state.sum} entered · ${state.remaining} remaining`;
+            tone = styles.neutral;
+        }
+    }
+
+    return (
+        <div className={`${styles.summary} ${tone}`} aria-live="polite">
+            {text}
+        </div>
+    );
+};
+
+export default SumEqualsSummary;

package/src/components/columns/ColumnRenderers.jsx

@@ -40,6 +40,55 @@ const buildToggleUrl = (urlTemplate, stageItem, rowData) => {
     return url;
 };
 
+/**
+ * Evaluate an opt-in stageConfig rule ({key, operator, value}) against one
+ * entry of a stage list. Absent rule -> false, so every setting that uses this
+ * is inert until a config asks for it.
+ *
+ * Operators: eq (default), neq, gte, gt, lte, lt, in. The comparison operators
+ * coerce to Number, because the values these rules match on arrive as strings
+ * from some payloads and as numbers from others, and a stage ordinal compared
+ * as a string sorts "10" below "2".
+ */
+const matchesStageRule = (rule, stageItem) => {
+    if (!rule || !rule.key || !stageItem) {
+        return false;
+    }
+
+    const value = stageItem[rule.key];
+
+    if (value === null || value === undefined) {
+        return false;
+    }
+
+    if (rule.operator === 'in') {
+        return (
+            Array.isArray(rule.value) &&
+            rule.value.some((candidate) => candidate == value)
+        );
+    }
+
+    const left = Number(value);
+    const right = Number(rule.value);
+    const comparable = !Number.isNaN(left) && !Number.isNaN(right);
+
+    switch (rule.operator) {
+        case 'neq':
+            return value != rule.value;
+        case 'gte':
+            return comparable && left >= right;
+        case 'gt':
+            return comparable && left > right;
+        case 'lte':
+            return comparable && left <= right;
+        case 'lt':
+            return comparable && left < right;
+        case 'eq':
+        default:
+            return value == rule.value;
+    }
+};
+
 const getStageStatus = (stageItem, toggleConfig) => {
     if (!toggleConfig || !toggleConfig.statusField) return null;
     
@@ -2895,6 +2944,30 @@ export const renderStageCounterColumn = ({ column, commonProps, navigate, onUpda
                             });
                         }
                         
+                        // `completeWhen` (opt-in): the rule that says this
+                        // entry is DONE as far as the grid showing it is
+                        // concerned, drawn as a rule through the label plus a
+                        // step back in weight.
+                        //
+                        // It lives in the view config rather than in the data
+                        // because "complete" is a statement about the VIEWER,
+                        // not about the entry: the same stage list is served
+                        // unchanged to every grid, and a member sitting at
+                        // Despatch is finished business to the Despatch list
+                        // while still being work in progress to Pickling. The
+                        // grid is the only party that knows which it is.
+                        //
+                        // Not a colour, on purpose: the pill's fill already
+                        // encodes the stage, and a second hue on a tablet in
+                        // daylight is the signal least likely to survive the
+                        // reading conditions. The rule through the label is
+                        // legible in glare and in greyscale; the fill stays as
+                        // it was, so nothing is lost by adding this.
+                        const isStageComplete = matchesStageRule(
+                            column.stageConfig.completeWhen,
+                            stageItem
+                        );
+
                         // Apply visual feedback for inactive stages
                         const stageStyle = {
                             width: useFullLabel ? 'auto' : '20px',
@@ -2911,7 +2984,21 @@ export const renderStageCounterColumn = ({ column, commonProps, navigate, onUpda
                             fontSize: '11px',
                             fontWeight: 'bold',
                             cursor: isToggleable ? 'pointer' : 'default',
-                            opacity: isStageActive ? 1 : 0.5,
+                            ...(isStageComplete
+                                ? {
+                                      textDecoration: 'line-through',
+                                      textDecorationThickness:
+                                          'var(--grid-stage-complete-thickness, 2px)',
+                                  }
+                                : {}),
+                            // An inactive toggle already mutes to 0.5; a
+                            // complete entry steps back a little less, so the
+                            // two states stay tellable apart when both apply
+                            opacity: !isStageActive
+                                ? 0.5
+                                : isStageComplete
+                                ? 'var(--grid-stage-complete-opacity, 0.65)'
+                                : 1,
                             transition: 'opacity 0.2s ease, transform 0.1s ease',
                             border: isToggleable ? '1px solid rgba(255,255,255,0.3)' : 'none',
                         };

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

@@ -1354,3 +1354,51 @@
 }
 
 
+
+/* =========================================================================
+   Row states (`ajaxSetting.rowStyles`)
+
+   A row tint is the first thing to go on a plant-floor tablet: pale fills
+   are chosen to sit under black text, which is exactly what makes them
+   vanish under glare or a low-angle view. The rows that carry these states
+   are the ones a crew scans a list FOR ("which of these headers is already
+   done?"), so the state has to survive the conditions the list is read in.
+
+   The treatment is therefore a rule through the text plus a step back in
+   ink weight — two signals, neither of them hue. Any `rowColours` tint on
+   the same row is untouched and becomes the redundant third.
+
+   Strike and ink are applied to the CELLS, not the row: the grid lays its
+   cells out absolutely, so `text-decoration` set on the row element has no
+   in-flow descendants to inherit it and would draw nothing.
+
+   Density hooks, per the `--nav-*` / `--grid-legend-*` convention above —
+   every declaration is `var(--hook, <the value it always had>)`, so an unset
+   hook is a no-op and a project retunes from `:root`:
+
+     --grid-row-complete-ink        struck-through text colour.
+                                    default: var(--muted-color, #6b7688)
+     --grid-row-complete-thickness  weight of the rule through the text.
+                                    default: 2px — heavier than the browser
+                                    default, which is hairline at this size.
+     --grid-row-complete-opacity    applies to non-text cell content (status
+                                    pills, icons), which a rule cannot cross.
+                                    default: 0.7
+   ========================================================================= */
+
+.rowComplete {
+    :global(.InovuaReactDataGrid__cell) {
+        color: var(--grid-row-complete-ink, var(--muted-color, #6b7688));
+        text-decoration: line-through;
+        text-decoration-thickness: var(--grid-row-complete-thickness, 2px);
+    }
+
+    // Cell content that is drawn rather than set — the action buttons, the
+    // stage pills, the boolean ticks — takes the muting alone, since a rule
+    // through the text cannot cross it.
+    :global(.InovuaReactDataGrid__cell) svg,
+    :global(.InovuaReactDataGrid__cell) img,
+    :global(.InovuaReactDataGrid__cell) button {
+        opacity: var(--grid-row-complete-opacity, 0.7);
+    }
+}

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

@@ -99,8 +99,65 @@
         display: grid;
         gap: 8px;
         margin-bottom: 12px;
-        
+        /*
+         * Cards carrying a companion field grow taller than bare ones.
+         * Stretching keeps every card in a row the same height, so two
+         * stations stay aligned while one of them is being filled in.
+         */
+        align-items: stretch;
+
         .checkboxItem {
+            /*
+             * A card is one unit: the option's checkbox, and — when
+             * `optionFields` maps one — its companion input underneath.
+             */
+            display: flex;
+            flex-direction: column;
+
+            /*
+             * With a companion inside, the card takes the frame and the label
+             * sheds its own, so the two read as one control instead of a box
+             * inside a box.
+             */
+            &.hasOptionField {
+                border: 1px solid var(--border-color, #e2e8f0);
+                border-radius: 6px;
+                background: var(--alternate-color, #fafbfc);
+                overflow: hidden;
+
+                > .checkboxLabel {
+                    border: 0;
+                    border-radius: 0;
+                    background: transparent;
+
+                    &:hover {
+                        transform: none;
+                        box-shadow: none;
+                    }
+                }
+            }
+
+            .optionField {
+                padding: 0 12px 10px;
+
+                /*
+                 * The companion is an ordinary form field that fills the card
+                 * instead of a row. Its own error styling (`.inputError`, a
+                 * red border on the input) is untouched, so a wrong quantity
+                 * still reads inside the card.
+                 */
+                > div {
+                    width: 100%;
+                    margin: 0;
+                    padding: 0;
+                }
+
+                label {
+                    font-size: var(--font-size-xs, 0.75rem);
+                    color: var(--muted-color, #6e7276);
+                }
+            }
+
             .checkboxLabel {
                 display: flex;
                 align-items: center;

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

@@ -0,0 +1,38 @@
+/*
+ * Live allocation line under a `sumEquals` field group.
+ *
+ * The height is fixed rather than content-driven: the line moves between
+ * "remaining", "allocated" and "over by" on every keystroke, and a form that
+ * grew and shrank a row underneath the inputs would push the fields around
+ * while the operator is typing into them.
+ */
+.summary {
+    display: flex;
+    align-items: center;
+    min-height: 1.25rem;
+    line-height: 1.25rem;
+    margin-top: var(--spacing-xs, 0.25rem);
+    font-size: var(--font-size-xs, 0.75rem);
+    font-weight: var(--font-weight-medium, 500);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+/* Still to allocate — informational, not a problem yet. */
+.neutral {
+    color: var(--muted-color, #6e7276);
+}
+
+/* Adds up: the same green the package uses for success elsewhere. */
+.balanced {
+    color: var(--success-color, #28a745);
+}
+
+/*
+ * Over the target. Matches the red `.inputError` puts on the inputs
+ * themselves, so the line and the fields read as one error.
+ */
+.over {
+    color: var(--danger-color, #dc3545);
+}