@visns-studio/visns-components 6.24.3 → 6.25.0

package/src/components/utils/cardLayout.js

@@ -0,0 +1,666 @@
+/**
+ * Which of a grid's columns become which part of a stacked phone row.
+ *
+ * No React and no CSS import, on the `utils/displayValue.js` precedent: this
+ * is the only new *logic* in the card treatment, it decides what 37 grid
+ * configs across three applications look like on a phone, and it is testable
+ * under `node --test` rather than by squinting at a rendered tree.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT THIS IS NOT
+ *
+ * It is not a second column pipeline. `deriveCardLayout` picks columns out of
+ * the array the view config already declares and hands them back; the DataGrid
+ * then calls the descriptor each of them was ALREADY built into, so every value
+ * on a card is formatted by the same renderer that formats it in the table.
+ * There is no per-type formatting in this file and there must never be one —
+ * that is how a currency starts rendering two different ways on two screens.
+ *
+ * The vocabulary is `title / subtitle / meta / badge / reference`, which is a
+ * card's vocabulary, but the rendered thing is a compact three-or-four line
+ * row. See the doctrine in `omnia-global-app`'s CustomersPage.jsx: "ROWS, NOT
+ * CARDS. … a card per client would be four times the height for the same four
+ * facts."
+ */
+
+/**
+ * The synthetic column's name.
+ *
+ * Exported because `DataGrid`'s row-click handler has to recognise it: the
+ * "ignore the last column" rule is positional, and in card mode the card is
+ * the last column.
+ */
+export const CARD_COLUMN_NAME = '__card';
+
+/**
+ * How many lines sit under the title, channels and meta together.
+ *
+ * Three at default density, four when the app is running `data-density="large"`
+ * — the roomier setting exists because somebody cannot read the tight one, so
+ * it buys a line rather than spending its extra height on padding alone.
+ */
+export const MAX_BODY_LINES = { default: 3, large: 4 };
+
+/** Column types that cannot be drawn on one clipped line of a fixed-height row. */
+const EXCLUDED_TYPES = new Set([
+    'placeholder',
+    'input_text',
+    'gallery',
+    'image',
+    'icons',
+    'colour',
+    'color',
+    'json',
+    'timer',
+    'total',
+    'stageCounter',
+    'richtext',
+]);
+
+/** Types that can carry a record's identity. `undefined` counts — most configs omit it. */
+const TEXTISH_TYPES = new Set(['text', 'relation', 'option', 'url']);
+
+const BADGE_TYPES = new Set(['option', 'boolean', 'stage']);
+
+/**
+ * Keys that name a record's state rather than a fact about it.
+ *
+ * The vocabulary exists because TYPE IS NOT ENOUGH IN EITHER DIRECTION: deals
+ * declare `stage` as `text`, and the tickets tabs declare `['status']` and
+ * `['priority']` as relations. Both are the chip a reader looks for first.
+ */
+const BADGE_KEYS =
+    /^(status|stage|state|priority|primary|active|disabled|is_default|invite_status)$/i;
+
+/** Keys that ARE the record's name. */
+const IDENTITY_KEYS =
+    /^(name|label|subject|title|display_name|full_name|pattern)$/i;
+
+const IDENTITY_SUFFIX = /_(name|label|title)$/i;
+
+/** …except when the suffix belongs to a PERSON, who is not this record's name. */
+const ATTRIBUTED_PREFIX = /^(owner|created_by|updated_by|assigned)/i;
+
+/**
+ * Keys that describe a person's part rather than identify them.
+ *
+ * This is what makes a contact's card read "Sarah Whitcombe / IT Manager"
+ * rather than putting the job title down among the meta. `title` is in BOTH
+ * this list and IDENTITY_KEYS, and the order of the steps is what resolves it:
+ * a view whose only identity is `title` titles on it (step 3b), while contacts
+ * take the name pair first (step 3a) and `title` is still in the pool when the
+ * subtitle is chosen.
+ */
+const DESCRIPTOR_KEYS =
+    /^(title|job_title|jobtitle|position|role|department)$/i;
+
+const FIRST_NAME_KEYS = /^(firstname|first_name|given_name)$/i;
+const LAST_NAME_KEYS = /^(surname|lastname|last_name|family_name)$/i;
+
+const EMAIL_KEYS = /(^|_)e?mail$/i;
+const TEL_KEYS =
+    /^(mobile|phone|telephone|work_phone|home_phone|fax|contact_number)$/i;
+
+/** The slots a per-column `"card"` value may name. */
+const CARD_SLOTS = new Set([
+    'title',
+    'subtitle',
+    'meta',
+    'badge',
+    'reference',
+    'hidden',
+]);
+
+/**
+ * The field a column is really about.
+ *
+ * Column ids in this library come in three spellings and all three appear in
+ * the same config file: a plain key, a dotted path into a loaded relation, and
+ * an ARRAY naming a relation chain (`['task','ticket']` is the ticket a task
+ * belongs to). The last segment is the field in every case.
+ *
+ * @param {object|string|Array} column a column definition, or a bare id
+ * @returns {string} `''` when there is nothing to read
+ */
+export const fieldKey = (column) => {
+    const id =
+        column && typeof column === 'object' && !Array.isArray(column)
+            ? column.id
+            : column;
+
+    if (Array.isArray(id)) {
+        const last = id[id.length - 1];
+
+        return last === null || last === undefined ? '' : String(last);
+    }
+
+    if (id === null || id === undefined) {
+        return '';
+    }
+
+    const text = String(id);
+    const dot = text.lastIndexOf('.');
+
+    return dot === -1 ? text : text.slice(dot + 1);
+};
+
+/**
+ * Is this key a machine's handle for the record rather than its name?
+ *
+ * `code` is deliberately NOT on the list. A product code is what a person says
+ * out loud when they ring up about one, and demoting it to a small grey chip
+ * would take the only readable thing off a products card.
+ *
+ * @param {string} key
+ * @returns {boolean}
+ */
+export const isIdLike = (key) => {
+    const text = String(key ?? '');
+
+    return /^(id|ref|reference)$/i.test(text) || /_(id|no)$/i.test(text);
+};
+
+/**
+ * Which contact channel a column carries, if any.
+ *
+ * THERE IS NO `email` COLUMN TYPE in this library — every address in every
+ * config is `type: "text"` with `id: "email"` — so the key has to be sniffed.
+ * The anchor is the whole point of the card treatment on a phone, and a
+ * `mailto:` on a column that merely mentions mail (`emailed_at`) is worse than
+ * none, so the pattern is anchored at both ends.
+ *
+ * `type: "mobile"` appears once in these configs (the client page's contacts
+ * tab), is not in the DataGrid's `renderColumn` switch and falls through to the
+ * text default. It is a phone here regardless of what the table does with it.
+ *
+ * @param {object} column
+ * @returns {'email'|'tel'|null}
+ */
+export const channelOf = (column) => {
+    if (!column) {
+        return null;
+    }
+
+    const key = fieldKey(column);
+
+    if (column.type === 'email' || EMAIL_KEYS.test(key)) {
+        return 'email';
+    }
+
+    if (column.type === 'phone' || column.type === 'mobile' || TEL_KEYS.test(key)) {
+        return 'tel';
+    }
+
+    return null;
+};
+
+const isTextish = (column) =>
+    column.type === undefined ||
+    column.type === null ||
+    TEXTISH_TYPES.has(column.type);
+
+const hasUsableLink = (column) =>
+    Boolean(column?.link && typeof column.link === 'object' && column.link.url);
+
+/**
+ * Does `candidate` — a string, a dotted path or an array — name this column?
+ *
+ * Both sides are reduced with `fieldKey`, so `"customer"`, `["customer"]` and
+ * `"deal.customer"` all find the same column. A config author should not have
+ * to know which of the three spellings the columns array happens to use.
+ */
+const namesColumn = (candidate, column) => {
+    const wanted = fieldKey(candidate);
+
+    return wanted !== '' && wanted === fieldKey(column);
+};
+
+/**
+ * The mapping the card renders from.
+ *
+ * @typedef {object} CardMapping
+ * @property {object|null} reference   small mono chip before the title
+ * @property {object|Array|null} title a column, or a `[first, last]` name pair
+ * @property {object|null} subtitle
+ * @property {object|null} badge
+ * @property {object[]} meta
+ * @property {object[]} channels       rendered as `tel:` / `mailto:` anchors
+ * @property {object[]} actionColumns  `type: 'action'` columns, folded into the rail
+ * @property {object[]} dropped        past the line budget — recorded, not rendered
+ * @property {object|null} link        the link the whole row follows
+ */
+
+/**
+ * Pick the parts of a card out of a view's declared columns.
+ *
+ * Returns `null` for "there is nothing here worth stacking" — no columns, an
+ * explicit `cardLayout: false`, or no column that could be a title. The caller
+ * treats `null` as "keep the scrolling grid exactly as it is today", which is
+ * why giving up is a first-class answer rather than a fallback that guesses.
+ *
+ * @param {object[]} columns the view config's `columns` array
+ * @param {object} [options]
+ * @param {object|false} [options.overrides] a `tableSetting.cardLayout` value
+ * @param {number} [options.maxLines] body-line budget; see MAX_BODY_LINES
+ * @param {(...args: any[]) => void} [options.log] where an unusable override is reported
+ * @returns {CardMapping|null}
+ */
+export const deriveCardLayout = (columns, options = {}) => {
+    const { overrides, maxLines, log } = options;
+
+    if (!Array.isArray(columns) || columns.length === 0) {
+        return null;
+    }
+
+    // `"cardLayout": false` is a view saying "not on this grid" and is the
+    // highest-precedence answer there is.
+    if (overrides === false) {
+        return null;
+    }
+
+    const note = typeof log === 'function' ? log : () => {};
+    const budget =
+        Number.isFinite(maxLines) && maxLines > 0
+            ? maxLines
+            : MAX_BODY_LINES.default;
+
+    /* ------------------------------------------------------------------
+       Step 1 — the pool.
+       ------------------------------------------------------------------ */
+    const actionColumns = [];
+    const explicit = { title: null, subtitle: null, badge: null, reference: null };
+    const explicitMeta = [];
+    let pool = [];
+
+    columns.forEach((column) => {
+        if (!column || typeof column !== 'object') {
+            return;
+        }
+
+        if (column.visible === false) {
+            return;
+        }
+
+        if (column.type === 'action') {
+            actionColumns.push(column);
+
+            return;
+        }
+
+        if (EXCLUDED_TYPES.has(column.type)) {
+            return;
+        }
+
+        const slot = CARD_SLOTS.has(column.card) ? column.card : null;
+
+        if (slot === 'hidden') {
+            return;
+        }
+
+        if (slot === 'meta') {
+            explicitMeta.push(column);
+
+            return;
+        }
+
+        if (slot && explicit[slot] === null) {
+            explicit[slot] = column;
+
+            return;
+        }
+
+        pool.push(column);
+    });
+
+    const take = (column) => {
+        pool = pool.filter((entry) => entry !== column);
+
+        return column;
+    };
+
+    /* ------------------------------------------------------------------
+       Step 0 — `tableSetting.cardLayout`, which short-circuits the slots it
+       names. Values are column ids; one that names no column is IGNORED with
+       a note rather than thrown, because a config typo must not take a phone's
+       whole grid down.
+       ------------------------------------------------------------------ */
+    const overridden = { ...explicit };
+    const overriddenMeta = [...explicitMeta];
+    // Whether a `cardLayout.meta` LIST was supplied. A per-column
+    // `card: "meta"` mark is a hint about one column and stays additive; a
+    // list is a statement about the whole body. See where it is spent below.
+    let metaIsClosed = false;
+    let overriddenLink = null;
+
+    if (overrides && typeof overrides === 'object') {
+        ['title', 'subtitle', 'badge', 'reference'].forEach((slot) => {
+            if (overrides[slot] === undefined || overrides[slot] === null) {
+                return;
+            }
+
+            const found = pool.find((column) =>
+                namesColumn(overrides[slot], column)
+            );
+
+            if (!found) {
+                note(
+                    `[cardLayout] "${slot}" names no column in this view:`,
+                    overrides[slot]
+                );
+
+                return;
+            }
+
+            overridden[slot] = take(found);
+        });
+
+        if (Array.isArray(overrides.meta)) {
+            metaIsClosed = true;
+
+            overrides.meta.forEach((candidate) => {
+                const found = pool.find((column) =>
+                    namesColumn(candidate, column)
+                );
+
+                if (!found) {
+                    note('[cardLayout] "meta" names no column in this view:', candidate);
+
+                    return;
+                }
+
+                overriddenMeta.push(take(found));
+            });
+        }
+
+        if (overrides.link && typeof overrides.link === 'object') {
+            overriddenLink = overrides.link;
+        }
+    }
+
+    /* ------------------------------------------------------------------
+       Step 2 — the reference chip.
+
+       Only among the first two columns a view declares. Every grid that leads
+       with a record number means it as a heading; a `customer_id` buried at
+       position six is a foreign key, and putting one in a mono chip at the top
+       of a card says something about the record that is not true.
+       ------------------------------------------------------------------ */
+    let reference = overridden.reference;
+
+    if (!reference) {
+        const candidate = pool
+            .slice(0, 2)
+            .find((column) => isIdLike(fieldKey(column)));
+
+        if (candidate) {
+            reference = take(candidate);
+        }
+    }
+
+    /* ------------------------------------------------------------------
+       Step 3 — the title, first match wins.
+       ------------------------------------------------------------------ */
+    let title = overridden.title;
+
+    if (!title) {
+        // 3a — a name pair. Two columns, one line: "Sarah Whitcombe", not
+        // "Sarah" with "Whitcombe" underneath it.
+        const first = pool.find((column) => FIRST_NAME_KEYS.test(fieldKey(column)));
+        const last = pool.find((column) => LAST_NAME_KEYS.test(fieldKey(column)));
+
+        if (first && last) {
+            title = [take(first), take(last)];
+        }
+    }
+
+    if (!title) {
+        // 3b — an exact identity key. THIS STEP EXISTS FOR /projects AND
+        // /opportunities, both of which declare the client relation FIRST: a
+        // "first substantive column" rule titles every one of their rows with
+        // the customer's name and hides the thing the row is about.
+        const candidate = pool.find(
+            (column) => isTextish(column) && IDENTITY_KEYS.test(fieldKey(column))
+        );
+
+        if (candidate) {
+            title = take(candidate);
+        }
+    }
+
+    if (!title) {
+        // 3c — an identity suffix (`site_name`, `product_label`), but not one
+        // that names a person who touched the record.
+        const candidate = pool.find((column) => {
+            const key = fieldKey(column);
+
+            return (
+                isTextish(column) &&
+                IDENTITY_SUFFIX.test(key) &&
+                !ATTRIBUTED_PREFIX.test(key)
+            );
+        });
+
+        if (candidate) {
+            title = take(candidate);
+        }
+    }
+
+    if (!title) {
+        // 3d — the first substantive text or relation. /ssa lands here and
+        // titles on the client, which is what its rows are read as.
+        const candidate = pool.find((column) => {
+            const key = fieldKey(column);
+
+            return (
+                (column.type === 'text' ||
+                    column.type === 'relation' ||
+                    column.type === 'relationArray' ||
+                    column.type === undefined ||
+                    column.type === null) &&
+                !isIdLike(key) &&
+                !BADGE_KEYS.test(key)
+            );
+        });
+
+        if (candidate) {
+            title = take(candidate);
+        }
+    }
+
+    // 3e — give up. A view of nothing but a rich-text note has no line worth
+    // making the heading, and a card whose title is a date is worse than the
+    // table it replaced.
+    if (!title) {
+        return null;
+    }
+
+    /* ------------------------------------------------------------------
+       Step 4 — the badge (at most one).
+       ------------------------------------------------------------------ */
+    let badge = overridden.badge;
+
+    if (!badge) {
+        const candidate = pool.find(
+            (column) =>
+                BADGE_TYPES.has(column.type) || BADGE_KEYS.test(fieldKey(column))
+        );
+
+        if (candidate) {
+            badge = take(candidate);
+        }
+    }
+
+    /* ------------------------------------------------------------------
+       Step 5 — the subtitle (at most one).
+
+       A relation, or a column whose key describes the record's part. Declared
+       order decides between them, so the client page's contacts tab reads
+       "Sarah Whitcombe / Head Office" (the site relation is declared first)
+       and the address book reads "Sarah Whitcombe / IT Manager".
+       ------------------------------------------------------------------ */
+    let subtitle = overridden.subtitle;
+
+    if (!subtitle) {
+        const candidate = pool.find(
+            (column) =>
+                column.type === 'relation' ||
+                column.type === 'relationArray' ||
+                (isTextish(column) && DESCRIPTOR_KEYS.test(fieldKey(column)))
+        );
+
+        if (candidate) {
+            subtitle = take(candidate);
+        }
+    }
+
+    /* ------------------------------------------------------------------
+       Steps 6 and 7 — the body lines, which channels and meta SHARE.
+
+       The order is: one channel of each kind, then meta, then any further
+       channels. That last clause is the rule that is not obvious and is the
+       one contacts turns on — a contact has an email, a mobile and a work
+       number, and the second phone number is the least useful of the four
+       remaining facts. One number to press is the point; two is a list.
+
+       Everything past the budget is recorded in `dropped` rather than silently
+       lost, so a view that is throwing something away can be found by reading
+       the mapping instead of by counting lines on a phone.
+       ------------------------------------------------------------------ */
+    const primaryChannels = [];
+    const extraChannels = [];
+    const metaCandidates = [];
+    const kindsTaken = new Set();
+
+    pool.forEach((column) => {
+        const kind = channelOf(column);
+
+        if (!kind) {
+            metaCandidates.push(column);
+
+            return;
+        }
+
+        if (kindsTaken.has(kind)) {
+            extraChannels.push(column);
+
+            return;
+        }
+
+        kindsTaken.add(kind);
+        primaryChannels.push(column);
+    });
+
+    // A `cardLayout.meta` LIST CLOSES THE META. It is an instruction, not a
+    // suggestion, and it does two things a per-column `card: "meta"` hint does
+    // not: it raises the budget rather than being trimmed by it (a view asking
+    // for four lines gets a taller row, which is honest; one asking for four
+    // and given three has been overruled without being told), and it stops the
+    // heuristic topping the list up. Branding profiles is what the second half
+    // is for — naming `created_at` and being handed two colour swatches
+    // alongside it is not what "the meta is created_at" means.
+    //
+    // Channels survive it, because the click-to-call line is the whole point
+    // of the treatment and no config author naming a meta list is asking for
+    // it to go.
+    const ordered = metaIsClosed
+        ? [...overriddenMeta, ...primaryChannels]
+        : [
+              ...overriddenMeta,
+              ...primaryChannels,
+              ...metaCandidates,
+              ...extraChannels,
+          ];
+    const lines = Math.max(
+        budget,
+        overriddenMeta.length + (metaIsClosed ? primaryChannels.length : 0)
+    );
+    const kept = ordered.slice(0, lines);
+    const dropped = [
+        ...ordered.slice(lines),
+        ...(metaIsClosed ? [...metaCandidates, ...extraChannels] : []),
+    ];
+
+    const channels = kept.filter((column) => channelOf(column) !== null);
+    const meta = kept.filter((column) => channelOf(column) === null);
+
+    /* ------------------------------------------------------------------
+       Step 8 — the link the whole row follows.
+
+       ONLY THE THREE COLUMNS THAT IDENTIFY THE RECORD are considered: the
+       title, the reference, the subtitle. "The first column carrying a link"
+       is the obvious wider rule and it is wrong — on /products and
+       /systemRequests the only column with a link is a FILE column whose href
+       is `/ajax/file/download/`, so the whole row would become a download.
+       That link belongs to that cell in the table and it still belongs to that
+       cell here; it is not a statement about where the record lives.
+
+       `null` is a legitimate answer: `onRowClick` then falls through to the
+       update modal, which is exactly what a tap on those rows does today.
+       ------------------------------------------------------------------ */
+    const titleColumn = Array.isArray(title) ? title[0] : title;
+    const link =
+        overriddenLink ??
+        [titleColumn, reference, subtitle].find(hasUsableLink)?.link ??
+        null;
+
+    return {
+        reference: reference ?? null,
+        title,
+        subtitle: subtitle ?? null,
+        badge: badge ?? null,
+        meta,
+        channels,
+        actionColumns,
+        dropped,
+        link,
+    };
+};
+
+/**
+ * The px geometry of a card row, per density.
+ *
+ * Not in `DENSITY_GRID`: those numbers are every existing deployment's table
+ * layout and `tests/density.test.mjs` pins them literally. These are new and
+ * belong to the one thing that reads them.
+ */
+export const CARD_METRICS = {
+    default: { padY: 10, title: 22, line: 18, gap: 2, railMin: 44 },
+    large: { padY: 12, title: 26, line: 21, gap: 3, railMin: 52 },
+};
+
+/**
+ * How tall every row of this grid is, in card mode.
+ *
+ * PER VIEW, NEVER PER ROW, and never measured. The virtual list positions rows
+ * absolutely from a height it is given, and `utils/useDensity.js` already
+ * records why measurement is the wrong tool on precisely this platform:
+ * "measurement is unreliable in a background-throttled tab and clips action
+ * buttons". A blank field therefore collapses its line's CONTENT and leaves
+ * the row exactly as tall as its neighbours, which is also what stops a list
+ * of cards looking like a ransom note.
+ *
+ * @param {CardMapping} mapping
+ * @param {object} [options]
+ * @param {'default'|'large'} [options.density]
+ * @param {boolean} [options.hasActions] whether the rail draws any control
+ * @returns {number} px
+ */
+export const cardRowHeight = (mapping, { density, hasActions } = {}) => {
+    const metrics = CARD_METRICS[density] || CARD_METRICS.default;
+    const { padY, title, line, gap, railMin } = metrics;
+
+    if (!mapping) {
+        return 2 * padY + Math.max(title, hasActions ? railMin : 0);
+    }
+
+    const bodyLines =
+        (mapping.subtitle ? 1 : 0) +
+        (mapping.channels?.length ?? 0) +
+        (mapping.meta?.length ?? 0);
+
+    const stack = title + bodyLines * (line + gap);
+
+    return 2 * padY + Math.max(stack, hasActions ? railMin : 0);
+};
+
+export default deriveCardLayout;