@visns-studio/visns-components 6.26.0 → 6.28.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
@@ -2167,6 +2212,7 @@ endpoint nor an Echo instance present it renders nothing and logs nothing.
 | `calendarPath` | `'/calendar'` | |
 | `callWorkspacePath` | `'/call/{number}'` | Template, or `(workspaceId, call) => path`. `{number}` is the `61…` form the workspace route expects. |
 | `syncChannelName` | `'throughlife-call-queue-pop'` | The `BroadcastChannel` that keeps every open tab's stack in step. Falsy switches cross-tab sync off. |
+| `clientDetailFields` | `CLIENT_DETAIL_FIELDS` (adviser / coding / age / city) | `[{ key, label, demo? }]` — the client-block rows, in card order; rows with an empty value are dropped; `demo` seeds the demo card. Pass your CRM's own fields so the card never names a field it does not have. Must be referentially stable (a module-scope constant, not an inline literal) — it sits in the demo effect's dependency list. |
 | `demoEnabled` | `true` | Registers `window.callPopDemo()` / `window.callPopClear()` for reviewing the UI without a backend. |
 
 **Payload contract.** Snake_case and camelCase are both accepted, so a Laravel
@@ -2181,6 +2227,11 @@ Named exports for testing: `toLocalDigits`, `formatAuPhone`, `formatEventDate`,
 `formatDueDate`, `toCallWorkspaceId`, `normaliseCall`, `normalisePickupCodes`,
 `formatElapsed`, `hasMonitorPermission`, `clientDetails`.
 
+`CLIENT_DETAIL_FIELDS`, `clientDetails` and `demoClientDetails` are exported
+from the package itself (`@visns-studio/visns-components`), so a host can build
+its own field list beside the default or reuse the demo seeding; the helpers
+module is not re-exported wholesale, only those three alongside the component.
+
 #### CallQueueSettings
 
 The admin table behind the pop: one row per Zoom call queue, carrying the

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.26.0",
+    "version": "6.28.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 &&

package/src/components/callQueue/CallQueuePop.jsx

@@ -40,6 +40,7 @@ import {
     defaultClientTasksUrl,
     defaultClientUrl,
     defaultTaskUrl,
+    demoClientDetails,
     directRingingLine,
     formatAuPhone,
     formatDueDate,
@@ -62,6 +63,7 @@ export {
     callBadgeLabel,
     calleeLabel,
     clientDetails,
+    demoClientDetails,
     directRingingLine,
     formatAuPhone,
     formatDueDate,
@@ -286,6 +288,16 @@ const CallQueuePop = ({
     calendarPath = '/calendar',
     callWorkspacePath = '/call/{number}',
     syncChannelName = SYNC_CHANNEL,
+    // The client-block rows, in card order — the host's own fields, so the
+    // card never names one its CRM does not have. The default is this
+    // component's original financial-planning shape (adviser / coding / age /
+    // city) and the demo card seeds itself from the same list, so a host that
+    // passes its own fields also demos its own fields.
+    //
+    // MUST be referentially stable — a module-scope constant, not an inline
+    // literal — because it sits in the demo effect's dependency list, and a
+    // fresh array per render would re-register the demo helpers every time.
+    clientDetailFields = CLIENT_DETAIL_FIELDS,
     demoEnabled = true,
     missedGraceMs = DEFAULT_MISSED_GRACE_MS,
 }) => {
@@ -680,20 +692,22 @@ const CallQueuePop = ({
                     queueName: 'Test Call Queue',
                     callerNumber: '+61298765432',
                     callerName: 'Margaret Chen',
-                    // Every field the server's client block can carry, so the
-                    // rich card can be reviewed without a real match. id 0
+                    // The rich card reviewed without a real match. The detail
+                    // rows are seeded from `clientDetailFields` itself, so the
+                    // demo shows exactly the host's own fields with the host's
+                    // own sample values rather than another CRM's. id 0
                     // renders the name as plain text, not a link.
                     client: {
                         id: 0,
                         name: 'Chen, Margaret (Mrs)',
                         matched_on: 'home',
-                        adviser: 'Alina Bailey',
-                        coding: 'Early Retirement',
-                        age: 66,
+                        // Before the spread, so a host listing `email` among
+                        // its own fields demos its own sample value while a
+                        // host that does not still gets one.
                         email: 'margaret.chen@example.com',
-                        city: 'Fremantle',
+                        ...demoClientDetails(clientDetailFields),
                         next_event: {
-                            title: 'Client - Annual Review',
+                            title: 'Client review',
                             date: new Date(
                                 Date.now() + 2 * 24 * 60 * 60 * 1000
                             ).toISOString(),
@@ -705,19 +719,19 @@ const CallQueuePop = ({
                     tasks: [
                         {
                             id: 90001,
-                            label: 'Confirm rollover paperwork',
+                            label: 'Confirm the site visit time',
                             due_date: new Date(
                                 Date.now() + 3 * 24 * 60 * 60 * 1000
                             ).toISOString(),
-                            task_type: 'Superannuation',
+                            task_type: 'Ticket',
                         },
                         {
                             id: 90002,
-                            label: 'Send updated risk profile questionnaire',
+                            label: 'Send the updated quote',
                             due_date: new Date(
                                 Date.now() + 9 * 24 * 60 * 60 * 1000
                             ).toISOString(),
-                            task_type: 'Insurance',
+                            task_type: 'Quote',
                         },
                     ],
                     startedAt: new Date().toISOString(),
@@ -745,6 +759,7 @@ const CallQueuePop = ({
         addDemoPickupCode,
         broadcastSync,
         clearCalls,
+        clientDetailFields,
         demoEnabled,
         dropDemoPickupCode,
     ]);
@@ -1707,7 +1722,7 @@ const CallQueuePop = ({
             {calls.map((call) => {
                 const pickupCode = pickupCodeFor(call);
                 const client = call.client;
-                const details = clientDetails(client);
+                const details = clientDetails(client, clientDetailFields);
                 const nextEvent = client?.next_event ?? null;
                 const nextEventDate = formatEventDate(nextEvent?.date);
                 const openTasks = Number(client?.open_tasks ?? 0);

package/src/components/callQueue/callQueueHelpers.js

@@ -210,32 +210,69 @@ export const defaultTaskUrl = (task) => `/tasks/detail/${task?.id}`;
 /** Default detail route for a matched client. */
 export const defaultClientUrl = (client) => `/clients/${client?.id}`;
 
-/** The client fields shown as label/value rows, in card order. */
+/**
+ * The client fields shown as label/value rows, in card order — the DEFAULT,
+ * inherited from the financial-planning CRM this component was ported from.
+ * Each entry's `demo` is the sample value the demo card shows for it.
+ *
+ * A host whose caller enrichment returns a different shape passes its own list
+ * as `clientDetailFields` rather than living with rows it can never fill.
+ */
 export const CLIENT_DETAIL_FIELDS = [
-    { key: 'adviser', label: 'Adviser' },
-    { key: 'coding', label: 'Coding' },
-    { key: 'age', label: 'Age' },
-    { key: 'city', label: 'City' },
+    { key: 'adviser', label: 'Adviser', demo: 'Alina Bailey' },
+    { key: 'coding', label: 'Coding', demo: 'Early Retirement' },
+    { key: 'age', label: 'Age', demo: 66 },
+    { key: 'city', label: 'City', demo: 'Fremantle' },
 ];
 
 /**
  * Detail rows for a client block, with the empty ones dropped — a card only
  * ever shows what the CRM actually knows, never a row with a blank value.
+ *
+ * `fields` is the host's own list, so the card only ever names fields its CRM
+ * actually has. An entry with no string `key` is malformed and is ignored
+ * rather than drawn as a row with nothing behind it.
  */
-export const clientDetails = (client) => {
+export const clientDetails = (client, fields = CLIENT_DETAIL_FIELDS) => {
     if (!client || typeof client !== 'object') {
         return [];
     }
 
-    return CLIENT_DETAIL_FIELDS.map(({ key, label }) => ({
-        label,
-        value: client[key],
-    })).filter(
-        (row) =>
-            row.value !== null &&
-            row.value !== undefined &&
-            String(row.value).trim() !== ''
-    );
+    const list = Array.isArray(fields) ? fields : CLIENT_DETAIL_FIELDS;
+
+    return list
+        .filter((field) => field && typeof field.key === 'string')
+        .map(({ key, label }) => ({
+            label,
+            value: client[key],
+        }))
+        .filter(
+            (row) =>
+                row.value !== null &&
+                row.value !== undefined &&
+                String(row.value).trim() !== ''
+        );
+};
+
+/**
+ * The demo card's client block, built from the same list the real card draws
+ * from — so a host passing its own fields sees its own fields in the demo
+ * rather than another CRM's. An entry carrying no `demo` contributes nothing.
+ */
+export const demoClientDetails = (fields = CLIENT_DETAIL_FIELDS) => {
+    const list = Array.isArray(fields) ? fields : CLIENT_DETAIL_FIELDS;
+
+    return list.reduce((carry, field) => {
+        if (!field || typeof field.key !== 'string') {
+            return carry;
+        }
+
+        if (field.demo === undefined) {
+            return carry;
+        }
+
+        return { ...carry, [field.key]: field.demo };
+    }, {});
 };
 
 /** Seconds since `startedAt` rendered as m:ss (never negative). */

package/src/components/styles/global-datagrid.css

@@ -715,11 +715,25 @@ body.tablet-mode .InovuaReactDataGrid__cell.cell-word-wrap > div {
 .InovuaReactDataGrid__cell {
     border: 0 !important;
     border-bottom: 1px solid var(--dgx-line) !important;
-    background: transparent !important;
     color: var(--dgx-ink) !important;
     font-size: 0.8125rem !important;
 }
 
+/* The same story as the row surface above, one level down. A per-column
+   `cellColours` tint arrives as an INLINE background on the CELL, and inline
+   loses to `!important` — so a blanket transparent cell would erase every
+   column tint a view configures. Cells carrying one are marked
+   `vs-datagrid--cell-tinted` (written by the column's className in
+   DataGrid.jsx) and this rule stands down for them; nothing else here paints
+   a cell, so the inline tint wins over the vendored theme's non-important
+   surface.
+   Hover and selected stay untouched because they are declared on the ROW and
+   the row's cell wrap, which sit BELOW the cell — the tint paints over them
+   and stays visible on hover, which is the point of tinting the cell. */
+.InovuaReactDataGrid__cell:not(.vs-datagrid--cell-tinted) {
+    background: transparent !important;
+}
+
 .InovuaReactDataGrid__cell__content {
     padding: 0 0.85rem !important;
     line-height: 1.45 !important;

package/src/index.js

@@ -141,6 +141,13 @@ import {
 import CallQueuePop from './components/callQueue/CallQueuePop';
 import CallQueueSettings from './components/callQueue/CallQueueSettings';
 import CallQueueDiagnostics from './components/callQueue/CallQueueDiagnostics';
+// The client-block field list and its two readers, so a host can build its own
+// `clientDetailFields` beside the default rather than restating the shape.
+import {
+    CLIENT_DETAIL_FIELDS,
+    clientDetails,
+    demoClientDetails,
+} from './components/callQueue/callQueueHelpers';
 import {
     CALL_POP_STATUS_EVENT,
     getCallPopStatus,
@@ -365,6 +372,9 @@ export {
     CallQueueDiagnostics,
     CallQueuePop,
     CallQueueSettings,
+    CLIENT_DETAIL_FIELDS,
+    clientDetails,
+    demoClientDetails,
     getCallPopStatus,
     updateCallPopStatus,
     cleanBase32,