@visns-studio/visns-components 6.24.4 → 6.25.0

package/src/components/auth/ClientAuthFrame.jsx

@@ -17,6 +17,11 @@ import AuthBrandPanel from './AuthBrandPanel';
  *             the other. A SECTION rather than a screen, sized by its parent —
  *             the consumer keeps its own header and footer and hands this the
  *             space between, which is why there is no `100vh` in its styles.
+ *
+ * A parent that has no height of its own to give — a bare router route element,
+ * say — therefore collapses the split to the height of the form. Wrap the step
+ * in `ClientAuthScreen` when it owns the page; that is what GenericAuth's
+ * client auth routes do.
  */
 const ClientAuthFrame = ({
     layout = 'card',

package/src/components/auth/ClientAuthScreen.jsx

@@ -0,0 +1,29 @@
+import React from 'react';
+
+import styles from '../styles/ClientAuth.module.scss';
+
+/**
+ * A client sign-in step given the whole viewport.
+ *
+ * ClientAuthFrame's `split` layout is a SECTION: it fills its parent and states
+ * no viewport height of its own, which is exactly what lets a consumer keep its
+ * own header and footer and hand the sign-in the space between. Mounted as a
+ * router route element there is no such parent — the route renders straight
+ * into the app's mount node, an auto-height block — so `height: 100%` resolved
+ * to the height of the form and the screen collapsed into a band at the top of
+ * the page.
+ *
+ * The staff screens never had the problem because their shell is
+ * `position: fixed; inset: 0`. This is the same promise made in flow layout, so
+ * a tall step two scrolls the page rather than being clipped by an overlay.
+ *
+ * Wrap a client auth step in this whenever it OWNS the page — which is what
+ * GenericAuth's `/{base}/login` and `/{base}/verify` routes do. Leave it off
+ * when embedding one inside chrome of your own; that is the case the section
+ * was written for.
+ */
+const ClientAuthScreen = ({ children }) => (
+    <div className={styles.screen}>{children}</div>
+);
+
+export default ClientAuthScreen;

package/src/components/columns/ColumnRenderers.jsx

@@ -15,6 +15,9 @@ import {
 } from '../../utils/relationshipSortingUtils';
 import { formatCellContent } from '../generic/shared/formatters';
 import { arrayCountFrom } from '../utils/displayValue';
+// One Australian numbering table, shared with the card row — see
+// `utils/contactChannels.js` for why it is not defined here any more.
+import { formatPhoneNumber } from '../utils/contactChannels';
 
 // Stage Toggle Utility Functions
 const buildToggleUrl = (urlTemplate, stageItem, rowData) => {
@@ -3170,52 +3173,6 @@ export const renderTotalColumn = () => {
     };
 };
 
-// Phone Number formatter
-const formatPhoneNumber = (phoneNumber) => {
-    if (!phoneNumber) return '';
-    
-    // Remove all non-digit characters
-    let cleanNumber = phoneNumber.replace(/\D/g, '');
-
-    // +61 spellings collapse to the local form so every branch below applies.
-    if (cleanNumber.match(/^61[2-9]\d{8}$/)) {
-        cleanNumber = '0' + cleanNumber.slice(2);
-    }
-    
-    // Check if it's an Australian mobile number (starts with 04 and has 10 digits)
-    if (cleanNumber.match(/^04\d{8}$/)) {
-        // Mobile format: 0400 000 000
-        return cleanNumber.replace(/(\d{4})(\d{3})(\d{3})/, '$1 $2 $3');
-    }
-    
-    // Check if it's a 1300/1800 number (10 digits starting with 1300 or 1800)
-    if (cleanNumber.match(/^1[38]00\d{6}$/)) {
-        // 1300/1800 format: 1300 000 000
-        return cleanNumber.replace(/(\d{4})(\d{3})(\d{3})/, '$1 $2 $3');
-    }
-    
-    // Check if it's an Australian landline number (8 digits with area code, or 10 digits total)
-    if (cleanNumber.match(/^0[2-9]\d{8}$/)) {
-        // Landline format: (02) 0000 0000
-        return cleanNumber.replace(/(\d{2})(\d{4})(\d{4})/, '($1) $2 $3');
-    }
-    
-    // If it doesn't match standard Australian patterns, return as is with some basic formatting
-    if (cleanNumber.length >= 8) {
-        // Generic formatting for longer numbers
-        if (cleanNumber.length === 8) {
-            return cleanNumber.replace(/(\d{4})(\d{4})/, '$1 $2');
-        } else if (cleanNumber.length === 9) {
-            return cleanNumber.replace(/(\d{1})(\d{4})(\d{4})/, '$1 $2 $3');
-        } else if (cleanNumber.length === 10) {
-            return cleanNumber.replace(/(\d{2})(\d{4})(\d{4})/, '($1) $2 $3');
-        }
-    }
-    
-    // Return original if no formatting pattern matches
-    return phoneNumber;
-};
-
 // ABN formatter
 const formatABN = (abn) => {
     if (!abn) return '';

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;