@visns-studio/visns-components 6.3.5 → 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.5",
+    "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
@@ -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/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);
+}