@visns-studio/visns-components 6.24.4 → 6.26.0

package/src/components/columns/StackedRow.jsx

@@ -0,0 +1,186 @@
+import { isBlankValue } from '../utils/displayValue';
+import { channelOf, fieldKey } from '../utils/cardLayout';
+import {
+    formatPhoneNumber,
+    mailtoHref,
+    telHref,
+} from '../utils/contactChannels';
+import styles from '../styles/StackedRow.module.scss';
+
+/**
+ * One grid row, drawn stacked instead of spread across columns.
+ *
+ * THIS IS A CELL, not a replacement for the row. It renders inside the single
+ * synthetic `__card` column the DataGrid mounts below 640px, which is what
+ * keeps everything else — the data source, the pager, selection, and above all
+ * `onRowClick`'s cell-index link resolution — working with nothing rewritten.
+ *
+ * IT FORMATS NOTHING ITSELF. Every value except a phone number comes back from
+ * `renderCell`, which calls the descriptor the column was already built into,
+ * so a currency on a card and the same currency in the table are the same
+ * string produced by the same code. The one exception is a channel: the phone
+ * column renderer formats a number and produces no `tel:`, which is the entire
+ * point of the treatment, so the anchor is built here from the shared
+ * `formatPhoneNumber`.
+ *
+ * @param {object} props
+ * @param {object} props.row the data row
+ * @param {object} props.mapping from `deriveCardLayout`
+ * @param {(column: object, row: object) => any} props.renderCell
+ * @param {(row: object) => any} [props.renderActions] the rail's controls
+ */
+const StackedRow = ({ row, mapping, renderCell, renderActions }) => {
+    // Belt and braces: card mode is hard-disabled for a grouped grid, and a
+    // tree parent is a summary with a fabricated id rather than a record. If
+    // either ever reaches here, draw nothing rather than a card claiming to be
+    // one of them.
+    if (!row || row.__treeParent || row.__group || !mapping) {
+        return null;
+    }
+
+    /**
+     * The raw field value, for the two decisions a rendered node cannot
+     * answer: is there anything here at all, and what goes in the `href`.
+     */
+    const rawValue = (column) => {
+        if (!column) {
+            return null;
+        }
+
+        const path = Array.isArray(column.id)
+            ? column.id
+            : String(column.id ?? '').split('.');
+
+        return path.reduce(
+            (value, segment) =>
+                value === null || value === undefined ? value : value[segment],
+            row
+        );
+    };
+
+    /** A rendered value, or `null` when the field is empty on this row. */
+    const cell = (column) => {
+        if (!column) {
+            return null;
+        }
+
+        const node = renderCell ? renderCell(column, row) : null;
+
+        return node === undefined || node === false ? null : node;
+    };
+
+    const title = Array.isArray(mapping.title)
+        ? // A NAME PAIR IS THE ONE PLACE THE RENDERERS ARE BYPASSED. Each of
+          // them wraps its value in a `width: 100%` ellipsis box, so two of
+          // them side by side each take the whole line and the surname is
+          // pushed off. A person's name has no formatting to lose.
+          mapping.title
+              .map((column) => rawValue(column))
+              .filter((value) => !isBlankValue(value))
+              .join(' ')
+        : cell(mapping.title);
+
+    const referenceValue = rawValue(mapping.reference);
+    const badge = cell(mapping.badge);
+    const subtitle = cell(mapping.subtitle);
+    const actions = renderActions ? renderActions(row) : null;
+
+    /**
+     * A channel line: the formatted number or address, as an anchor.
+     *
+     * `stopPropagation` on the anchor, not `preventDefault` — the tap has to
+     * reach the dialer, it just must not also open the record behind it.
+     */
+    const channelLine = (column, index) => {
+        const value = rawValue(column);
+
+        if (isBlankValue(value)) {
+            return null;
+        }
+
+        const kind = channelOf(column);
+        const href = kind === 'email' ? mailtoHref(value) : telHref(value);
+        const text =
+            kind === 'email' ? String(value).trim() : formatPhoneNumber(value);
+
+        return (
+            // Keyed on the INDEX as well as the field: a view can declare two
+            // columns with the same last id segment (brandingProfiles has
+            // three `['colors']` columns) and React would drop all but one.
+            <div className={styles.line} key={`channel-${index}-${fieldKey(column)}`}>
+                {href ? (
+                    <a
+                        className={styles.channel}
+                        href={href}
+                        onClick={(event) => event.stopPropagation()}
+                    >
+                        {text}
+                    </a>
+                ) : (
+                    <span className={styles.lineValue}>{text}</span>
+                )}
+            </div>
+        );
+    };
+
+    /**
+     * A meta line: the column's label, then its value.
+     *
+     * The label is carried because a bare date under a bare name is a fact
+     * nobody can read — "Closing 14/09/2026" and "14/09/2026" are not the same
+     * line. A blank field collapses to nothing and the ROW STAYS THE SAME
+     * HEIGHT, which is what stops a list of records looking like a ransom note.
+     */
+    const metaLine = (column, index) => {
+        const value = cell(column);
+
+        if (value === null || isBlankValue(rawValue(column))) {
+            return null;
+        }
+
+        return (
+            <div className={styles.line} key={`meta-${index}-${fieldKey(column)}`}>
+                {column.label ? (
+                    <span className={styles.lineLabel}>{column.label}</span>
+                ) : null}
+                <span className={styles.lineValue}>{value}</span>
+            </div>
+        );
+    };
+
+    return (
+        <div className={styles.card}>
+            <div className={styles.main}>
+                <div className={styles.titleRow}>
+                    {isBlankValue(referenceValue) ? null : (
+                        <span className={styles.reference}>
+                            {String(referenceValue)}
+                        </span>
+                    )}
+                    <div className={styles.title}>{title}</div>
+                </div>
+
+                {subtitle === null ||
+                isBlankValue(rawValue(mapping.subtitle)) ? null : (
+                    <div className={styles.subtitle}>{subtitle}</div>
+                )}
+
+                {(mapping.channels || []).map(channelLine)}
+                {(mapping.meta || []).map(metaLine)}
+            </div>
+
+            {badge === null && !actions ? null : (
+                <div className={styles.rail}>
+                    {badge === null ? null : (
+                        <div className={styles.badge}>{badge}</div>
+                    )}
+                    {actions ? (
+                        <div className={styles.actions}>{actions}</div>
+                    ) : null}
+                </div>
+            )}
+        </div>
+    );
+};
+
+export default StackedRow;

package/src/components/controls/DataGridSearch.jsx

@@ -1,3 +1,4 @@
+import { useState } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { openRecordWindow } from '../utils/popupWindow';
 import { toast } from 'react-toastify';
@@ -7,9 +8,12 @@ import {
     Plus,
     Search,
     ArrowUpDown,
+    Rows3,
+    Table,
     Upload,
 } from 'lucide-react';
 import Download from '../Download';
+import DataGridSortSheet from './DataGridSortSheet';
 import styles from '../styles/DataGrid.module.scss';
 
 const DataGridSearch = ({
@@ -26,8 +30,21 @@ const DataGridSearch = ({
     pageSetting,
     // Bulk upload
     onBulkUploadClick,
+    // Card mode. `cardCapable` is "this grid is narrow AND a mapping was
+    // derived" — the only condition under which either of these two controls
+    // means anything, so above 640px nothing below renders and the toolbar is
+    // the one it has always been.
+    cardCapable = false,
+    cardMode = false,
+    onCardModeChange,
+    columns,
+    columnsMetadata,
+    sortBy,
+    sort,
+    onSort,
 }) => {
     const navigate = useNavigate();
+    const [sortSheetOpen, setSortSheetOpen] = useState(false);
 
     const handleChangeSearch = (e) => {
         const { value } = e.target;
@@ -90,6 +107,60 @@ const DataGridSearch = ({
         navigate(sortUrl, { state: newState });
     };
 
+    /**
+     * The two card-mode controls, and they only exist below 640px.
+     *
+     * SORT replaces the job the column headers were doing before
+     * `showHeader={false}` took them away. THE TABLE TOGGLE is the escape
+     * hatch for the job they were doing that this pass does NOT replace: the
+     * filter row. A per-column filter needs per-column chrome and there is one
+     * column here, so a reader who needs to filter presses Table and gets the
+     * whole grid back — sideways scroll, filter row and all — for as long as
+     * this tab is open.
+     *
+     * Drawn as icon squares rather than labelled buttons because they sit
+     * beside Add New on a 340px screen, and three labelled buttons on that row
+     * wrap onto two lines.
+     */
+    const renderCardControls = () => {
+        if (!cardCapable) {
+            return null;
+        }
+
+        return (
+            <>
+                {cardMode ? (
+                    <button
+                        type="button"
+                        className={styles.cardControl}
+                        aria-label="Sort"
+                        title="Sort"
+                        onClick={() => setSortSheetOpen(true)}
+                    >
+                        <ArrowUpDown strokeWidth={2} size={16} />
+                    </button>
+                ) : null}
+                <button
+                    type="button"
+                    className={styles.cardControl}
+                    aria-pressed={!cardMode}
+                    aria-label={cardMode ? 'Show as a table' : 'Show as cards'}
+                    title={cardMode ? 'Show as a table' : 'Show as cards'}
+                    onClick={() =>
+                        onCardModeChange &&
+                        onCardModeChange(cardMode ? 'table' : 'cards')
+                    }
+                >
+                    {cardMode ? (
+                        <Table strokeWidth={2} size={16} />
+                    ) : (
+                        <Rows3 strokeWidth={2} size={16} />
+                    )}
+                </button>
+            </>
+        );
+    };
+
     const renderCreateButton = () => {
         if (form.createDisable && form.createDisable === true) {
             return null;
@@ -209,16 +280,47 @@ const DataGridSearch = ({
     const isSearchEnabled = !(form.searchDisable === true);
     const isCreateDisabled = form.createDisable === true;
 
-    // Don't render anything if both search and create are disabled
+    const sortSheet =
+        sortSheetOpen && cardMode ? (
+            <DataGridSortSheet
+                columns={columns}
+                columnsMetadata={columnsMetadata}
+                sortBy={sortBy}
+                sort={sort}
+                onSort={onSort}
+                onClose={() => setSortSheetOpen(false)}
+            />
+        ) : null;
+
+    // Don't render anything if both search and create are disabled — unless
+    // card mode is on, in which case this is the ONLY place Sort and Table can
+    // live and a grid without them cannot be sorted or filtered at all.
     if (!isSearchEnabled && isCreateDisabled) {
-        return null;
+        if (!cardCapable) {
+            return null;
+        }
+
+        return (
+            <div className={styles.actionButtonsContainer}>
+                <div className={styles.actionButtonsStandalone}>
+                    {renderCardControls()}
+                </div>
+                {sortSheet}
+            </div>
+        );
     }
 
     // If search is disabled but create button is enabled, render only the button with its own container
     if (!isSearchEnabled && !isCreateDisabled) {
         return (
             <div className={styles.actionButtonsContainer}>
+                {cardCapable ? (
+                    <div className={styles.actionButtonsStandalone}>
+                        {renderCardControls()}
+                    </div>
+                ) : null}
                 {renderCreateButton()}
+                {sortSheet}
             </div>
         );
     }
@@ -254,8 +356,14 @@ const DataGridSearch = ({
                 />
             </div>
             <div className={styles.actionButtonsWrapper}>
+                {cardCapable ? (
+                    <div className={styles.actionButtonsStandalone}>
+                        {renderCardControls()}
+                    </div>
+                ) : null}
                 {!isCreateDisabled && renderCreateButton()}
             </div>
+            {sortSheet}
         </div>
     );
 };

package/src/components/controls/DataGridSortSheet.jsx

@@ -0,0 +1,155 @@
+import { ArrowDown, ArrowUp, Check } from 'lucide-react';
+import StandardModal from '../generic/StandardModal';
+import { isColumnSortable } from '../../utils/columnsMetadataUtils';
+import styles from '../styles/DataGrid.module.scss';
+
+/**
+ * Sorting, with the column headers gone.
+ *
+ * In card mode the grid is drawn with `showHeader={false}`, which takes the
+ * column headers AND the filter row away in one prop — and a header click is
+ * how a grid has always been sorted. It is not the only caller of
+ * `handleSort({ id, dir })` though: that writes `sortBy`/`sort` into
+ * `config.ajaxSetting`, which the controlled `sortInfo` prop reads and the next
+ * request carries. So this sheet is a second caller of the same function, not a
+ * second sort implementation, and there is no new state and no extra fetch.
+ *
+ * SORT SURVIVES THE COLUMN SET. `computedSortInfo` comes straight from the
+ * prop and is never validated against the mounted columns, so a grid showing
+ * one synthetic `__card` column still sorts on `firstname`.
+ *
+ * WHICH COLUMNS ARE OFFERED, and the two independent reasons one is not:
+ *
+ *   - `sortable: false` in the view config — an accessor computed per row
+ *     (`owner_label`), or a relation the backend cannot order by.
+ *   - the server's own `columns_metadata`, the same answer the column headers
+ *     ask `isColumnSortable` for. Offering a control that answers 500 is worse
+ *     than not offering it.
+ *
+ * A column whose id is an ARRAY is a relation chain and has no single column
+ * name to order by, so it is offered only where the config names one in
+ * `sort`. That is deliberately conservative: the server's allow-list takes real
+ * column names, and a guess that reaches it comes back as an error the reader
+ * cannot act on.
+ *
+ * @param {object} props
+ * @param {object[]} props.columns the view config's columns
+ * @param {object} props.columnsMetadata the server's per-column metadata
+ * @param {string|null} props.sortBy currently sorted field
+ * @param {string|null} props.sort `'asc'` | `'desc'`
+ * @param {(value: {id: string, dir: number}) => void} props.onSort
+ * @param {() => void} props.onClose
+ */
+const DataGridSortSheet = ({
+    columns,
+    columnsMetadata,
+    sortBy,
+    sort,
+    onSort,
+    onClose,
+}) => {
+    const options = (columns || [])
+        .map((column) => {
+            if (!column || column.visible === false || column.type === 'action') {
+                return null;
+            }
+
+            const name =
+                column.sort ??
+                (Array.isArray(column.id) ? null : column.id ?? null);
+
+            if (!name || column.sortable === false) {
+                return null;
+            }
+
+            if (!isColumnSortable(name, columnsMetadata)) {
+                return null;
+            }
+
+            return { name: String(name), label: column.label || String(name) };
+        })
+        .filter(Boolean)
+        // A view can declare the same field twice (one column linking to the
+        // record, another to its client); one row per field is what a reader
+        // expects to choose from.
+        .filter(
+            (option, index, all) =>
+                all.findIndex((other) => other.name === option.name) === index
+        );
+
+    const apply = (name, dir) => {
+        onSort({ id: name, dir });
+        onClose();
+    };
+
+    return (
+        <StandardModal
+            isOpen
+            onClose={onClose}
+            title="Sort"
+            variant="sheet"
+            size="small"
+            showHeader
+        >
+            <div className={styles.sortSheet}>
+                {options.length === 0 ? (
+                    <p className={styles.sortSheetEmpty}>
+                        Nothing on this list can be sorted.
+                    </p>
+                ) : (
+                    options.map((option) => {
+                        const active = sortBy === option.name;
+
+                        return (
+                            <div
+                                className={styles.sortSheetRow}
+                                key={option.name}
+                            >
+                                <span className={styles.sortSheetLabel}>
+                                    {active ? (
+                                        <Check size={14} strokeWidth={2.5} />
+                                    ) : null}
+                                    {option.label}
+                                </span>
+                                {/* Both directions are always drawn, and the
+                                    current one is marked. A single button that
+                                    toggles makes the reader press it to find
+                                    out which way it is going to go. */}
+                                <span className={styles.sortSheetDirections}>
+                                    <button
+                                        type="button"
+                                        aria-label={`Sort by ${option.label}, ascending`}
+                                        aria-pressed={active && sort === 'asc'}
+                                        className={
+                                            active && sort === 'asc'
+                                                ? `${styles.sortSheetDirection} ${styles.sortSheetDirectionOn}`
+                                                : styles.sortSheetDirection
+                                        }
+                                        onClick={() => apply(option.name, 1)}
+                                    >
+                                        <ArrowUp size={16} strokeWidth={2} />
+                                    </button>
+                                    <button
+                                        type="button"
+                                        aria-label={`Sort by ${option.label}, descending`}
+                                        aria-pressed={active && sort === 'desc'}
+                                        className={
+                                            active && sort === 'desc'
+                                                ? `${styles.sortSheetDirection} ${styles.sortSheetDirectionOn}`
+                                                : styles.sortSheetDirection
+                                        }
+                                        onClick={() => apply(option.name, -1)}
+                                    >
+                                        <ArrowDown size={16} strokeWidth={2} />
+                                    </button>
+                                </span>
+                            </div>
+                        );
+                    })
+                )}
+            </div>
+        </StandardModal>
+    );
+};
+
+export default DataGridSortSheet;

package/src/components/generic/GenericAuth.jsx

@@ -21,6 +21,10 @@ import Verify from '../auth/Verify';
 import TwoFactorAuth from '../auth/TwoFactorAuth';
 import ClientLogin from '../auth/ClientLogin';
 import ClientOTPVerify from '../auth/ClientOTPVerify';
+// Both client steps are route elements here, so they own the page and have to
+// say so: the split layout is sized by a parent that, on a bare route, has no
+// height to give. See ClientAuthScreen.
+import ClientAuthScreen from '../auth/ClientAuthScreen';
 import {
     resolveAuthEndpoints,
     resolveClientPaths,
@@ -100,6 +104,14 @@ const GenericAuth = ({
     clientPortalConfig = null, // Configuration for client portal with component and URLs
     config = {}, // Configuration object for auth features
     density = 'default', // 'default' | 'large' — app-wide display density
+    // Whether every DataGrid in this app draws stacked card rows below 640px
+    // instead of a table that scrolls sideways. Opt-in per APPLICATION, not
+    // per library version: the mapping that decides what a card says is a
+    // heuristic over a view's columns, and three apps consume this library —
+    // a title picked badly on a screen nobody has looked at is worse than the
+    // sideways table it replaced. A single view can still opt itself in with
+    // `tableSetting.cardLayout`, and out with `cardLayout: false`.
+    cardRows = false,
     // Every URL the auth journey talks to, merged over the 6.6.3 literals.
     // Threaded from here into each screen so one object configures the lot.
     // See auth/authEndpoints.js for the keys and their defaults.
@@ -154,6 +166,22 @@ const GenericAuth = ({
         };
     }, [density]);
 
+    // Same mechanism, same node, same reasoning: `useCardRowsEnabled` in
+    // utils/useDensity.js reads this attribute off <html>, so an app opts its
+    // grids in from one place and every grid — including one mounted inside a
+    // modal on a detail tab — sees it without a prop being threaded to it.
+    // Absent means absent: an app that never passes the prop writes no
+    // attribute and nothing in the DataGrid changes.
+    useInsertionEffect(() => {
+        if (typeof document === 'undefined' || !cardRows) {
+            return undefined;
+        }
+        document.documentElement.setAttribute('data-card-rows', 'on');
+        return () => {
+            document.documentElement.removeAttribute('data-card-rows');
+        };
+    }, [cardRows]);
+
     const updateAuthStatus = async () => {
         // The loading curtain covers two moments and stays down for neither
         // more nor less: the first profile check of a page load (no usable
@@ -539,15 +567,17 @@ const ClientLoginComponent = React.memo(
         paths,
         options,
     }) => (
-        <ClientLogin
-            loginBg={loginBg}
-            logo={logo}
-            setSystemAuth={setIsAuthenticated}
-            setUserProfile={setUserProfile}
-            urls={urls}
-            paths={paths}
-            {...(options || {})}
-        />
+        <ClientAuthScreen>
+            <ClientLogin
+                loginBg={loginBg}
+                logo={logo}
+                setSystemAuth={setIsAuthenticated}
+                setUserProfile={setUserProfile}
+                urls={urls}
+                paths={paths}
+                {...(options || {})}
+            />
+        </ClientAuthScreen>
     )
 );
 
@@ -561,15 +591,17 @@ const ClientOTPVerifyComponent = React.memo(
         paths,
         options,
     }) => (
-        <ClientOTPVerify
-            loginBg={loginBg}
-            logo={logo}
-            setSystemAuth={setIsAuthenticated}
-            setUserProfile={setUserProfile}
-            urls={urls}
-            paths={paths}
-            {...(options || {})}
-        />
+        <ClientAuthScreen>
+            <ClientOTPVerify
+                loginBg={loginBg}
+                logo={logo}
+                setSystemAuth={setIsAuthenticated}
+                setUserProfile={setUserProfile}
+                urls={urls}
+                paths={paths}
+                {...(options || {})}
+            />
+        </ClientAuthScreen>
     )
 );
 

package/src/components/generic/GenericDashboard.jsx

@@ -1297,7 +1297,26 @@ function GenericDashboard({ setting, userProfile, dynamicDashboard = false }) {
     };
 
     const renderWidget = (widget) => {
-        const widgetData = data[widget.id] || [];
+        const rawWidgetData = data[widget.id];
+        /*
+         * `??` FOR A COUNTER, AND THAT IS THE WHOLE OF A LONG-STANDING BUG.
+         *
+         * A counter's value is a scalar and ZERO IS A PERFECTLY GOOD ONE —
+         * no unassigned tickets, no support hours left. `|| []` swapped that
+         * zero for an empty array, and the `typeof` gate on the value below
+         * (number or string, or else ` `) then rejected the array and
+         * drew a blank. So the two cards reporting the best possible news
+         * were the two that rendered as an empty box with a button under it,
+         * at every width, while the card reporting one open ticket worked.
+         *
+         * Everything else keeps the `|| []` it has always had: a chart handed
+         * a falsy scalar where it expects rows throws inside the chart
+         * library, and `[]` is the shape those widgets already fall back to.
+         */
+        const widgetData =
+            widget.type === 'counter'
+                ? rawWidgetData ?? []
+                : rawWidgetData || [];
 
         // More detailed check for valid data
         const hasData =