@visns-studio/visns-components 5.24.0 → 5.26.0

package/package.json

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

package/src/components/DataGrid.jsx

@@ -530,6 +530,15 @@ const DataGrid = forwardRef(
                         if (gridRef.current?.api) {
                             gridRef.current.api.forceUpdate();
                         }
+
+                        // Restore the scroll position captured by handleReload,
+                        // after forceUpdate so the re-render can't clobber it
+                        const pending = pendingScrollRestoreRef.current;
+                        if (pending && gridRef.current) {
+                            pendingScrollRestoreRef.current = null;
+                            gridRef.current.setScrollTop?.(pending.top);
+                            gridRef.current.setScrollLeft?.(pending.left);
+                        }
                     }, 50); // Increased delay to ensure proper rendering consistency
                 });
 
@@ -545,6 +554,8 @@ const DataGrid = forwardRef(
         const [gridColumns, setGridColumns] = useState([]);
         const [columnsMetadata, setColumnsMetadata] = useState({});
         const gridRef = useRef(null);
+        // Scroll position waiting to be re-applied after a data reload
+        const pendingScrollRestoreRef = useRef(null);
 
         // Get default limit from userProfile preferences, tableSetting, or default to 25
         const getDefaultLimit = () => {
@@ -1388,6 +1399,19 @@ const DataGrid = forwardRef(
         };
 
         const handleReload = () => {
+            // Preserve the user's scroll position across the reload: the
+            // datagrid resets to the top when its dataSource resolves, so
+            // capture here and restore once the new data has rendered
+            // (see the dataSource callback).
+            const scrollTop = gridRef.current?.getScrollTop?.() ?? 0;
+            const scrollLeft = gridRef.current?.getScrollLeft?.() ?? 0;
+            if (scrollTop > 0 || scrollLeft > 0) {
+                pendingScrollRestoreRef.current = {
+                    top: scrollTop,
+                    left: scrollLeft,
+                };
+            }
+
             gridRef.current.paginationProps.reload();
 
             // Force grid to recalculate row heights after reload

package/src/components/Field.jsx

@@ -22,6 +22,7 @@ import {
     Minus,
     ArrowLeft,
     Trash2,
+    TriangleAlert,
     X,
     Lightbulb,
 } from 'lucide-react';
@@ -75,6 +76,41 @@ function insertVariableAtCursor(el, token) {
     });
 }
 
+/**
+ * Interpolate {placeholders} in a conflict warning template with values
+ * from the in-use info returned by the field's `conflict.url` endpoint.
+ */
+function formatConflictMessage(template, info) {
+    return template.replace(/\{(\w+)\}/g, (match, key) => info[key] ?? '');
+}
+
+/**
+ * Evaluate the opt-in `readOnlyWhen` field setting against the form data:
+ * an array of {id, value, operator} rules; the field is read-only when ANY
+ * rule matches. Operators: eq (default), neq, notEmpty.
+ */
+function evaluateReadOnlyWhen(rules, data) {
+    if (!Array.isArray(rules) || rules.length === 0) {
+        return false;
+    }
+
+    return rules.some((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;
+        }
+    });
+}
+
 function Field({
     api,
     autocompleteCallback,
@@ -122,6 +158,165 @@ function Field({
     const [emailSuggestions, setEmailSuggestions] = useState([]);
     const [showEmailSuggestions, setShowEmailSuggestions] = useState(false);
 
+    /**
+     * Conflict warnings (opt-in via `settings.conflict`): the field polls
+     * `conflict.url` for a map of {optionId: info} describing options that
+     * are currently in use elsewhere, warns when a selected option appears
+     * in that map, and toasts when a busy option is newly selected. Inert
+     * when the setting is absent.
+     */
+    const [conflictMap, setConflictMap] = useState({});
+    // null = first run; skips the assignment-time toast for values that
+    // were already selected when the form opened
+    const prevConflictSelectionRef = useRef(null);
+
+    // Opt-in conditional read-only (e.g. lock the header selector once an
+    // item has entered Pickling); inert when `readOnlyWhen` is absent
+    const isFieldReadOnly =
+        settings.readOnly === true ||
+        evaluateReadOnlyWhen(settings.readOnlyWhen, formData);
+    const conflictExcludeValue =
+        settings.conflict?.excludeKey != null
+            ? formData?.[settings.conflict.excludeKey]
+            : undefined;
+
+    useEffect(() => {
+        const conflict = settings.conflict;
+
+        if (
+            !conflict?.url ||
+            !['multi-dropdown', 'multi-dropdown-ajax'].includes(settings.type)
+        ) {
+            return;
+        }
+
+        let active = true;
+
+        const payload = {};
+        if (conflict.excludeParam && conflictExcludeValue != null) {
+            payload[conflict.excludeParam] = conflictExcludeValue;
+        }
+
+        const fetchConflicts = async () => {
+            try {
+                const res = await CustomFetch(conflict.url, 'POST', payload);
+
+                if (active && res?.data && res.data.error === '') {
+                    setConflictMap(res.data.data || {});
+                }
+            } catch (err) {
+                console.error(err);
+            }
+        };
+
+        fetchConflicts();
+
+        // Refresh while the field is mounted so the warning tracks what is
+        // actually happening on the floor without a manual reload
+        const intervalId = setInterval(
+            fetchConflicts,
+            (conflict.interval ?? 5) * 1000
+        );
+
+        return () => {
+            active = false;
+            clearInterval(intervalId);
+        };
+    }, [settings.conflict?.url, settings.type, conflictExcludeValue]);
+
+    const conflictWarnings = useMemo(() => {
+        const conflict = settings.conflict;
+
+        if (!conflict || !Array.isArray(inputValue)) {
+            return [];
+        }
+
+        return inputValue
+            .filter(
+                (item) =>
+                    item && conflictMap[String(item.id ?? item.value)]
+            )
+            .map((item) => {
+                const info = conflictMap[String(item.id ?? item.value)];
+
+                return formatConflictMessage(
+                    conflict.message ||
+                        '"{label}" is already in use on Job #{job_number} ({customer})',
+                    {
+                        ...info,
+                        label:
+                            item.label ?? item.name ?? info.label ?? '',
+                    }
+                );
+            });
+    }, [settings.conflict, inputValue, conflictMap]);
+
+    useEffect(() => {
+        if (!settings.conflict || !Array.isArray(inputValue)) {
+            return;
+        }
+
+        const selectedIds = inputValue
+            .filter((item) => item)
+            .map((item) => String(item.id ?? item.value));
+
+        if (prevConflictSelectionRef.current === null) {
+            prevConflictSelectionRef.current = selectedIds;
+            return;
+        }
+
+        const added = selectedIds.filter(
+            (id) => !prevConflictSelectionRef.current.includes(id)
+        );
+        prevConflictSelectionRef.current = selectedIds;
+
+        added.forEach((id) => {
+            const info = conflictMap[id];
+
+            if (info) {
+                toast.warning(
+                    formatConflictMessage(
+                        settings.conflict.message ||
+                            '"{label}" is already in use on Job #{job_number} ({customer})',
+                        info
+                    )
+                );
+            }
+        });
+    }, [inputValue, conflictMap, settings.conflict]);
+
+    /**
+     * Surface the in-use state inside the dropdown menu itself: MultiSelect
+     * already renders an option `description`, so busy options get one.
+     * Pass-through when no conflict setting or nothing is busy.
+     */
+    const decorateOptionsWithConflicts = (list) => {
+        if (
+            !settings.conflict ||
+            !Array.isArray(list) ||
+            Object.keys(conflictMap).length === 0
+        ) {
+            return list;
+        }
+
+        return list.map((option) => {
+            const info = conflictMap[String(option.id ?? option.value)];
+
+            if (!info) {
+                return option;
+            }
+
+            return {
+                ...option,
+                description: formatConflictMessage(
+                    settings.conflict.optionMessage ||
+                        'In use — Job #{job_number} ({customer})',
+                    info
+                ),
+            };
+        });
+    };
+
     /** Canvas States */
     const [canvasPopupOpen, setCanvasPopupOpen] = useState(false);
     const [canvasUrl, setCanvasUrl] = useState('');
@@ -1918,13 +2113,14 @@ function Field({
                                     ? ''
                                     : inputValue
                             }
-                            options={
+                            options={decorateOptionsWithConflicts(
                                 settings.type === 'multi-dropdown'
                                     ? settings.options
                                     : options
-                            }
+                            )}
                             isSearchable={settings.isSearchable ?? true}
                             isCreatable={settings.isCreatable ?? false}
+                            isDisabled={isFieldReadOnly}
                             creatableConfig={settings.creatableConfig || {}}
                             dataOptions={dataOptions}
                             style={style}
@@ -3224,6 +3420,39 @@ function Field({
                     Tip: Type to create new entries and press Enter
                 </div>
             )}
+            {conflictWarnings.length > 0 && (
+                <div
+                    style={{
+                        display: 'flex',
+                        flexDirection: 'column',
+                        gap: '4px',
+                        marginTop: '4px',
+                    }}
+                >
+                    {conflictWarnings.map((message, index) => (
+                        <div
+                            key={index}
+                            style={{
+                                fontSize: '0.8rem',
+                                color: '#92400e',
+                                backgroundColor: '#fef3c7',
+                                border: '1px solid #f59e0b',
+                                borderRadius: '4px',
+                                padding: '4px 8px',
+                                display: 'flex',
+                                alignItems: 'center',
+                                gap: '6px',
+                            }}
+                        >
+                            <TriangleAlert
+                                size={14}
+                                style={{ flexShrink: 0 }}
+                            />
+                            <span>{message}</span>
+                        </div>
+                    ))}
+                </div>
+            )}
             {renderAdditionalContainer()}
             <StandardModal
                 isOpen={childFormShow}

package/src/components/Form.jsx

@@ -65,6 +65,32 @@ const optimizeImageIfNeeded = async (file) => {
     return file;
 };
 
+/**
+ * Evaluate an opt-in `disableWhen` rule ({id, value, operator, message})
+ * against the form data. Used by save buttons (e.g. saveAnother) to disable
+ * themselves conditionally. Operators: eq (default), notEmpty,
+ * arrayLengthGte (value = minimum length).
+ */
+const evaluateDisableWhen = (rule, data) => {
+    if (!rule || !rule.id) {
+        return false;
+    }
+
+    const value = data?.[rule.id];
+
+    switch (rule.operator) {
+        case 'arrayLengthGte':
+            return Array.isArray(value) && value.length >= (rule.value ?? 0);
+        case 'notEmpty':
+            return Array.isArray(value)
+                ? value.length > 0
+                : value != null && value !== '';
+        case 'eq':
+        default:
+            return value == rule.value;
+    }
+};
+
 function Form({
     ajaxSetting,
     api,
@@ -1149,6 +1175,28 @@ function Form({
                 e.preventDefault();
 
                 const { type } = e.target.dataset;
+
+                // Guard: a conditionally-disabled saveAnother must not run
+                // even if a stale render left the button clickable
+                if (type === 'saveAnother') {
+                    const saveAnotherSettings =
+                        formType === 'update'
+                            ? formSettings.update?.saveAnother
+                            : formSettings.create?.saveAnother;
+                    const disableWhen = saveAnotherSettings?.disableWhen;
+
+                    if (
+                        disableWhen &&
+                        evaluateDisableWhen(disableWhen, formData)
+                    ) {
+                        toast.warning(
+                            disableWhen.message ||
+                                'This action is currently unavailable.'
+                        );
+                        return;
+                    }
+                }
+
                 let fields = formSettings.fields;
                 let _inputClass = inputClass;
                 let validation = '';
@@ -3341,18 +3389,55 @@ function Form({
                                                 </button>
                                                 {formSettings.update?.hasOwnProperty(
                                                     'saveAnother'
-                                                ) && (
-                                                    <button
-                                                        className={styles.btn}
-                                                        onClick={handleSubmit}
-                                                        data-type="saveAnother"
-                                                    >
-                                                        {formSettings.update
-                                                            .saveAnother
-                                                            ?.label ||
-                                                            'Save & Create Another'}
-                                                    </button>
-                                                )}
+                                                ) &&
+                                                    (() => {
+                                                        const disableWhen =
+                                                            formSettings.update
+                                                                .saveAnother
+                                                                ?.disableWhen;
+                                                        const isDisabled =
+                                                            disableWhen
+                                                                ? evaluateDisableWhen(
+                                                                      disableWhen,
+                                                                      formData
+                                                                  )
+                                                                : false;
+
+                                                        return (
+                                                            <button
+                                                                className={
+                                                                    styles.btn
+                                                                }
+                                                                onClick={
+                                                                    handleSubmit
+                                                                }
+                                                                data-type="saveAnother"
+                                                                disabled={
+                                                                    isDisabled
+                                                                }
+                                                                title={
+                                                                    isDisabled
+                                                                        ? disableWhen?.message ||
+                                                                          ''
+                                                                        : undefined
+                                                                }
+                                                                style={
+                                                                    isDisabled
+                                                                        ? {
+                                                                              opacity: 0.5,
+                                                                              cursor: 'not-allowed',
+                                                                          }
+                                                                        : undefined
+                                                                }
+                                                            >
+                                                                {formSettings
+                                                                    .update
+                                                                    .saveAnother
+                                                                    ?.label ||
+                                                                    'Save & Create Another'}
+                                                            </button>
+                                                        );
+                                                    })()}
                                                 {formSettings.update?.hasOwnProperty(
                                                     'saveExit'
                                                 ) && (

package/src/components/MultiSelect.jsx

@@ -144,6 +144,7 @@ function MultiSelect({
     style,
     isCreatable = false,
     isSearchable = true,
+    isDisabled = false,
     creatableConfig = {},
 }) {
     const [selectOptions, setSelectOptions] = useState([]);
@@ -249,23 +250,37 @@ function MultiSelect({
 
     const handleCreate = async (inputValue) => {
         if (creatableConfig.url && creatableConfig.method) {
+            // creatableConfig.payload lets the consumer send extra fields
+            // with the create (e.g. {is_active: 1}); creatableConfig.field
+            // overrides the body key for the typed value (default "label",
+            // e.g. "name" for entities whose label column is `name`).
+            const valueKey = creatableConfig.field || 'label';
             const res = await CustomFetch(
                 creatableConfig.url,
                 creatableConfig.method,
-                { label: inputValue }
+                { [valueKey]: inputValue, ...(creatableConfig.payload || {}) }
             );
 
-            if (res && res.data) {
+            const created = res?.data?.data ?? res?.data;
+            if (res && created && created.id) {
                 const newOption = {
-                    value: res.data.id,
-                    label: res.data.label || inputValue,
-                    // Make sure description is preserved if it exists in the response
-                    description: res.data.description || null,
-                    ...res.data,
+                    value: created.id,
+                    label: created.label || created.name || inputValue,
+                    description: created.description || null,
+                    ...created,
                 };
 
+                const nextValue = [...selectValue, newOption];
                 setSelectOptions((prevOptions) => [...prevOptions, newOption]);
-                setSelectValue((prevValues) => [...prevValues, newOption]);
+                setSelectValue(nextValue);
+                // Propagate to the parent form so the freshly-created option
+                // is part of the field value and is persisted on save —
+                // updating local state alone left it out of the submission.
+                onChange(
+                    nextValue,
+                    { action: 'create-option', option: newOption },
+                    settings.id
+                );
             }
         }
     };
@@ -297,6 +312,7 @@ function MultiSelect({
             isSearchable={isSearchable}
             isMulti={multi}
             isCreatable={isCreatable}
+            isDisabled={isDisabled}
             filterOption={createFilter({ ignoreAccents: false })}
             components={{
                 SelectList,

package/src/components/columns/ColumnRenderers.jsx

@@ -731,9 +731,66 @@ export const renderMultiDropdownColumn = ({
                         ).toLowerCase()
                 );
 
+            const save = (ids) => {
+                if (
+                    column.update?.key &&
+                    column.update?.url &&
+                    column.update?.method
+                ) {
+                    handleDropdownUpdate(
+                        column.update.key,
+                        `${column.update.url}/${data.id}`,
+                        column.update.method,
+                        ids
+                    );
+                }
+            };
+
+            // creatable: typing a value not in the list offers "Add …"
+            // which POSTs a new entry to the source entity and adds it to
+            // this row's selection.
+            const handleCreate = async (inputValue) => {
+                const label = String(inputValue ?? '').trim();
+                if (
+                    !label ||
+                    !column.creatable?.url ||
+                    !column.creatable?.field
+                ) {
+                    return;
+                }
+                try {
+                    const res = await CustomFetch(
+                        column.creatable.url,
+                        'POST',
+                        {
+                            [column.creatable.field]: label,
+                            ...(column.creatable.payload || {}),
+                        }
+                    );
+                    const created = res?.data?.data;
+                    if (res?.data?.error === '' && created?.id) {
+                        save([
+                            ...value.map((v) => v.value),
+                            created.id,
+                        ]);
+                    } else {
+                        toast.error(
+                            res?.data?.error || 'Could not create entry'
+                        );
+                    }
+                } catch (err) {
+                    console.error(err);
+                    toast.error('Could not create entry');
+                }
+            };
+
+            const SelectComponent = column.creatable
+                ? CreatableSelect
+                : Select;
+
             return (
                 <div>
-                    <Select
+                    <SelectComponent
                         isMulti
                         options={options}
                         value={value}
@@ -746,20 +803,13 @@ export const renderMultiDropdownColumn = ({
                         }
                         menuPlacement="auto"
                         styles={compactSelectStyles}
-                        onChange={(selected) => {
-                            if (
-                                column.update?.key &&
-                                column.update?.url &&
-                                column.update?.method
-                            ) {
-                                handleDropdownUpdate(
-                                    column.update.key,
-                                    `${column.update.url}/${data.id}`,
-                                    column.update.method,
-                                    (selected || []).map((s) => s.value)
-                                );
-                            }
-                        }}
+                        {...(column.creatable && {
+                            onCreateOption: handleCreate,
+                            formatCreateLabel: (v) => `Add "${v}"`,
+                        })}
+                        onChange={(selected) =>
+                            save((selected || []).map((s) => s.value))
+                        }
                     />
                     {otherSelected && (
                         <OtherValueInput
@@ -2639,6 +2689,10 @@ export const renderStageCounterColumn = ({ column, commonProps, navigate, onUpda
 
                     // Create an array of squares based on the stage data
                     const squares = [];
+                    // labelMode 'full' (opt-in) renders the whole label
+                    // instead of just its first character
+                    const useFullLabel =
+                        column.stageConfig.labelMode === 'full';
                     for (let i = 0; i < stageCount; i++) {
                         // Get the stage item
                         const stageItem = stageData[i];
@@ -2661,21 +2715,27 @@ export const renderStageCounterColumn = ({ column, commonProps, navigate, onUpda
                                 typeof rawValue === 'object' &&
                                 rawValue.name
                             ) {
-                                labelValue = rawValue.name.charAt(0);
+                                labelValue = useFullLabel
+                                    ? rawValue.name
+                                    : rawValue.name.charAt(0);
                             }
                             // If it's a string, use the first character
                             else if (
                                 typeof rawValue === 'string' &&
                                 rawValue.length > 0
                             ) {
-                                labelValue = rawValue.charAt(0);
+                                labelValue = useFullLabel
+                                    ? rawValue
+                                    : rawValue.charAt(0);
                             }
                             // Otherwise use the raw value if it can be converted to string
                             else if (
                                 rawValue !== null &&
                                 rawValue !== undefined
                             ) {
-                                labelValue = String(rawValue).charAt(0);
+                                labelValue = useFullLabel
+                                    ? String(rawValue)
+                                    : String(rawValue).charAt(0);
                             }
                         }
 
@@ -2704,6 +2764,18 @@ export const renderStageCounterColumn = ({ column, commonProps, navigate, onUpda
                             }
                         }
 
+                        // tooltipKey (opt-in): a stage-item field holding the
+                        // full tooltip text (e.g. "Header 12 — Galvanizing")
+                        if (
+                            column.stageConfig.tooltipKey &&
+                            stageItem &&
+                            stageItem[column.stageConfig.tooltipKey]
+                        ) {
+                            tooltipContent = String(
+                                stageItem[column.stageConfig.tooltipKey]
+                            );
+                        }
+
                         // Determine the background color based on stageColour configuration
                         let backgroundColor = 'var(--primary-color, #4a90e2)';
 
@@ -2761,7 +2833,9 @@ export const renderStageCounterColumn = ({ column, commonProps, navigate, onUpda
                         
                         // Apply visual feedback for inactive stages
                         const stageStyle = {
-                            width: '20px',
+                            width: useFullLabel ? 'auto' : '20px',
+                            minWidth: '20px',
+                            padding: useFullLabel ? '0 6px' : '0',
                             height: '20px',
                             backgroundColor: backgroundColor,
                             borderRadius: '3px',