@visns-studio/visns-components 6.3.4 → 6.3.6

package/package.json

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

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
@@ -2182,6 +2194,21 @@ function Field({
                         isEditable={settings.isEditable ?? false}
                         creatableConfig={settings.creatableConfig || {}}
                         editableConfig={settings.editableConfig || {}}
+                        // The checkbox renderer previously ignored the field's
+                        // read-only state, leaving `readOnlyWhen` configs
+                        // 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';
@@ -91,6 +95,56 @@ const evaluateDisableWhen = (rule, data) => {
     }
 };
 
+/**
+ * Field visibility rules (`show`).
+ *
+ * A field carries `show: [{ id: '<other field id>', <condition> }]`, meaning
+ * "when MY value satisfies this condition, reveal the named field; otherwise
+ * hide it". With `self: true` the roles swap: the condition is read from the
+ * NAMED field's value and applied to the field carrying the rule.
+ *
+ * Supported conditions:
+ *
+ *   { value: [...] }    the value equals one of the listed literals. What
+ *                       toggles ({ value: [true] }) and radios
+ *                       ({ value: [1, 2] }) use.
+ *
+ *   { minSelected: n }  the value is an array holding at least n entries.
+ *                       For the multi-* types (multi-checkbox-ajax,
+ *                       multi-dropdown-ajax, …) whose value is a list of
+ *                       selected options — e.g. reveal a pair of per-item
+ *                       quantity inputs only once two boxes are ticked.
+ *
+ * Rules are evaluated when the record loads (the effect keyed on
+ * `fetchTrigger`) and again on every change to the field that carries them,
+ * so a revealed field cannot linger after the value that revealed it goes
+ * away. See also `required_rely` (required-ness that follows another field's
+ * value) and `sumEquals` (a group of numbers that must total a target).
+ */
+const hasShowCondition = (condition) =>
+    !!condition &&
+    (condition.minSelected !== undefined ||
+        (Array.isArray(condition.value) && condition.value.length > 0));
+
+const matchesShowCondition = (condition, value) => {
+    if (!condition) {
+        return false;
+    }
+
+    if (condition.minSelected !== undefined) {
+        return (
+            Array.isArray(value) &&
+            value.length >= Number(condition.minSelected)
+        );
+    }
+
+    if (Array.isArray(condition.value)) {
+        return condition.value.includes(value);
+    }
+
+    return false;
+};
+
 function Form({
     ajaxSetting,
     api,
@@ -465,18 +519,71 @@ function Form({
             });
         };
 
+        /**
+         * Re-evaluate this field's `show` rules against the value it has just
+         * been given. The other two change handlers do this from the DOM
+         * node's `data-show`, which a select / multi-checkbox never emits, so
+         * without this a rule on one of those types would only ever run at
+         * load time — the reveal would not follow the user's clicks.
+         */
+        const applyShowConditions = (newValue) => {
+            const sourceField = formSettings.fields.find((f) => f.id === id);
+            const conditions = sourceField?.show || [];
+
+            if (conditions.length === 0) {
+                return;
+            }
+
+            const _fields = [...formSettings.fields];
+            let changed = false;
+
+            conditions.forEach((showObject) => {
+                if (!showObject?.id || !hasShowCondition(showObject)) {
+                    return;
+                }
+
+                const targetIndex = _fields.findIndex(
+                    (f) => f.id === showObject.id
+                );
+
+                if (targetIndex < 0) {
+                    return;
+                }
+
+                const shouldShow = matchesShowCondition(showObject, newValue);
+                const target = showObject.self
+                    ? _fields.find((f) => f.id === id)
+                    : _fields[targetIndex];
+
+                if (target) {
+                    target.hide = !shouldShow;
+                    changed = true;
+                }
+            });
+
+            if (changed && updateForm) {
+                updateForm((prevState) => ({
+                    ...prevState,
+                    fields: _fields,
+                }));
+            }
+        };
+
         // // Switch cases to handle different actions
         switch (action.action) {
             case 'select-option':
             case 'create-option': // New case to handle create-option
             case 'deselect-option': // Handle unchecking tags
                 handleSelectOption();
+                applyShowConditions(inputValue);
                 break;
             case 'clear':
                 updateFormData({ [id]: '' });
+                applyShowConditions([]);
                 break;
             case 'remove-value':
                 updateFormData({ [id]: inputValue });
+                applyShowConditions(inputValue);
                 break;
         }
     };
@@ -1303,6 +1410,82 @@ function Form({
                                 _inputClass[item.id] = styles.inputError;
                             }
                         }
+
+                        /**
+                         * `sumEquals`: a set of numeric fields that must add
+                         * up to a target.
+                         *
+                         *   sumEquals: {
+                         *       fields: ['qty_a', 'qty_b'],
+                         *       equals: 'qty_total',   // field id, or a number
+                         *       message: '…'           // optional override
+                         *   }
+                         *
+                         * Declared once, on any one of the fields in the
+                         * group. Every named field is marked in error so the
+                         * user sees which inputs to reconcile, not just a
+                         * message.
+                         *
+                         * The rule is skipped while its own field is hidden,
+                         * so a group that only appears in a revealed section
+                         * (see the `show` documentation above) cannot block an
+                         * 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;
+                            // 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 (state) {
+                                const labelFor = (fieldId) =>
+                                    fields.find((f) => f.id === fieldId)
+                                        ?.label || fieldId;
+                                const groupLabels = state.ids
+                                    .map(labelFor)
+                                    .join(' and ');
+
+                                const markGroup = () =>
+                                    state.ids.forEach((fieldId) => {
+                                        _inputClass[fieldId] =
+                                            styles.inputError;
+                                    });
+
+                                if (state.emptyIds.length > 0) {
+                                    validation += `${groupLabels} are required.<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();
+                                }
+                            }
+                        }
                     });
 
                     setInputClass(_inputClass);
@@ -2676,9 +2859,9 @@ function Form({
             const showConditions = field.show || [];
 
             showConditions.forEach((showObject) => {
-                const { id, value, self } = showObject;
+                const { id, self } = showObject;
 
-                if (id != '' && value.length > 0) {
+                if (id != '' && hasShowCondition(showObject)) {
                     const targetField = formSettings.fields.find(
                         (f) => f.id === id
                     );
@@ -2695,7 +2878,10 @@ function Form({
                             valueChecker !== undefined &&
                             valueChecker !== null
                         ) {
-                            const shouldShow = value.includes(valueChecker);
+                            const shouldShow = matchesShowCondition(
+                                showObject,
+                                valueChecker
+                            );
 
                             if (self) {
                                 field.hide = !shouldShow;
@@ -2716,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}>
@@ -2774,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}`}>
@@ -3444,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

@@ -16,6 +16,31 @@ function MultiCheckbox({
     isEditable = false,
     creatableConfig = {},
     editableConfig = {},
+    // The checkbox renderer used to ignore the field's read-only state, so a
+    // `readOnlyWhen` config claimed a lock the UI never enforced (the same
+    // 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([]);
@@ -75,8 +100,12 @@ function MultiCheckbox({
     const filteredOptions = checkboxOptions;
 
     const handleCheckboxChange = (option, isChecked) => {
+        if (disabled) {
+            return;
+        }
+
         let newSelected;
-        
+
         if (isChecked) {
             // Add to selection
             newSelected = [...selectedValues, option];
@@ -182,11 +211,33 @@ 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}>
 
             {/* Create new tag section */}
-            {isCreatable && (
+            {isCreatable && !disabled && (
                 <div className={styles.createSection}>
                     {!isCreating ? (
                         <button
@@ -248,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
@@ -294,9 +356,10 @@ function MultiCheckbox({
                                     checked={isSelected(option.id)}
                                     onChange={(e) => handleCheckboxChange(option, e.target.checked)}
                                     className={styles.checkbox}
+                                    disabled={disabled}
                                 />
                                 <span className={styles.labelText}>{option.label}</span>
-                                {isEditable && (
+                                {isEditable && !disabled && (
                                     <button
                                         type="button"
                                         onClick={(e) => {
@@ -312,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/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);
+}