@visns-studio/visns-components 6.25.0 → 6.27.0

package/README.md

@@ -9,6 +9,51 @@ A comprehensive React component library used by the VISNS Studio team for CRM an
 
 VISNS Components is a React-based UI component library that provides a set of reusable, consistent, and customizable components for building web applications. It includes components for authentication, data grids, forms, navigation, and more, designed to work seamlessly together.
 
+## Recent Updates (v6.27.0)
+
+### A tint on one column: `cellColours`
+
+A DataGrid could already tint a whole ROW from its data —
+`ajaxSetting.rowColours`, first match wins:
+
+```js
+ajaxSetting: {
+    rowColours: [{ id: 'priority', value: 'high', colour: '#FFCDD2' }],
+}
+```
+
+Which is the right instrument for "this record needs attention" and the wrong
+one for "these are Sam's". A grid where every row is coloured has no signal
+left in colour at all — the eye stops reading it after the second full-width
+band. `cellColours` is the same rule shape declared on a COLUMN, painted onto
+that one cell:
+
+```js
+{
+    id: ['owner'],
+    label: 'Owner',
+    type: 'relation',
+    nameFrom: 'name',
+    cellColours: [
+        { id: 'owner_id', value: 19, colour: '#E1BEE7' },
+        { id: 'owner_id', value: 30, colour: '#BBDEFB' },
+    ],
+}
+```
+
+- **`id` names a field on the ROW, not on the column.** The value worth
+  matching is usually the id sitting behind the label the column renders
+  (`owner_id` under an Owner relation column), and the cell never shows it.
+- **Loose equality**, as `rowStyles` uses — a JSON config writes `19` and an
+  API hands back `"19"`, and a config author should not have to know which.
+- **First match wins**, as `rowColours` does. A cell has one background.
+- **Every column type**, because the rule is applied by the shared column
+  `style`, not by any one renderer — relation, text, date, currency alike.
+- **It composes with `rowColours`.** The row tint is a background on the row
+  element and the cell's own paints on top of it, so a tinted cell reads as
+  itself on a tinted row, and keeps its colour under the hover surface (which
+  is also below the cell).
+
 ## Recent Updates (v6.17.0)
 
 ### A client's text messages, on the client's own page

package/package.json

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

package/src/components/DataGrid.jsx

@@ -128,6 +128,31 @@ const ROW_STYLE_CLASSES = {
     complete: styles.rowComplete,
 };
 
+/**
+ * First matching per-column `cellColours` rule for a row.
+ *
+ *   cellColours: [
+ *       { id: 'owner_id', value: 19, colour: '#E1BEE7' }
+ *   ]
+ *
+ * The column-level twin of `ajaxSetting.rowColours`: the same rule shape,
+ * painted onto ONE cell instead of the whole row. A grid where every row is
+ * tinted is a grid with no signal left, so a view that only needs to tell its
+ * owners apart tints the Owner column and leaves the rest of the row alone.
+ *
+ * `id` names a field on the ROW, not on the column, because the value worth
+ * matching is usually the id sitting behind the label the column renders
+ * (`owner_id` under an Owner relation column) and the cell never shows it.
+ *
+ * Loose equality, as `rowStyles` uses: a JSON config writes 19 and an API
+ * hands back "19", and a config author should not have to know which. First
+ * match wins, as `rowColours` does — a cell has exactly one background.
+ */
+const findCellColour = (column, data) =>
+    Array.isArray(column?.cellColours) && data
+        ? column.cellColours.find((rule) => data[rule.id] == rule.value)
+        : undefined;
+
 import '@visns-studio/visns-datagrid-enterprise/index.css';
 
 import CustomFetch from './Fetch';
@@ -4438,6 +4463,26 @@ const DataGrid = forwardRef(
                             columnsMetadata
                         );
 
+                        // A `cellColours` tint is an inline background on the
+                        // cell, and global-datagrid.css paints every cell
+                        // `background: transparent !important` (it has to
+                        // outrank the vendored theme) — inline loses to
+                        // `!important`, so the tint would never be seen. The
+                        // literal class marks the cells that carry one and
+                        // that rule stands down for them, exactly as
+                        // `vs-datagrid--row-tinted` does a level up. The
+                        // hover and selected surfaces live on the ROW, so the
+                        // tint keeps painting over them and survives a hover.
+                        const cellColourClassName = (cellProps, extra = '') =>
+                            [
+                                findCellColour(column, cellProps?.data)
+                                    ? 'vs-datagrid--cell-tinted'
+                                    : '',
+                                extra,
+                            ]
+                                .filter(Boolean)
+                                .join(' ');
+
                         const commonProps = {
                             header: column.label,
                             defaultFlex: 1,
@@ -4481,7 +4526,7 @@ const DataGrid = forwardRef(
                                     ? style.text_vertical_align
                                     : 'center',
                             style: (cellProps) => {
-                                const { id, value } = cellProps;
+                                const { id, value, data } = cellProps;
                                 let columnStyle = {};
 
                                 if (
@@ -4501,8 +4546,24 @@ const DataGrid = forwardRef(
                                     };
                                 }
 
+                                // `cellColours` last, so a column's static
+                                // `style` cannot quietly outrank the rule the
+                                // view asked for. It paints over any
+                                // `rowColours` tint for this one cell without
+                                // touching it: the row tint is a background on
+                                // the ROW element and this one sits on the cell
+                                // above it.
+                                const cellColour = findCellColour(column, data);
+
+                                if (cellColour) {
+                                    columnStyle.backgroundColor =
+                                        cellColour.colour;
+                                }
+
                                 return columnStyle;
                             },
+                            className: (cellProps) =>
+                                cellColourClassName(cellProps),
                             type: column.type,
                         };
 
@@ -4966,9 +5027,13 @@ const DataGrid = forwardRef(
                                     name: columnId,
                                     filterEditor: filterEditor,
                                     filterEditorProps: filterEditorProps,
-                                    className: finalWordWrap
-                                        ? 'cell-word-wrap'
-                                        : '',
+                                    className: (cellProps) =>
+                                        cellColourClassName(
+                                            cellProps,
+                                            finalWordWrap
+                                                ? 'cell-word-wrap'
+                                                : ''
+                                        ),
                                     render: ({ data }) => {
                                         if (
                                             data &&