@visns-studio/visns-components 6.20.0 → 6.21.0

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.20.0",
+    "version": "6.21.0",
     "description": "Various packages to assist in the development of our Custom Applications.",
     "main": "src/index.js",
     "files": [

package/src/components/generic/GenericIndex.jsx

@@ -301,6 +301,12 @@ function GenericIndex({
     themeType,
     userProfile,
     showTitle = true,
+    /* Whether the embedded "N total" count (and tableInfo headings) render
+       when showTitle is off. Defaults on — normally it is the only place
+       the row count prints above the fold. A host that embeds the grid
+       under its own summary strip is already printing that figure and
+       turns this off rather than saying the same number twice. */
+    showTotal = true,
     tabLayout = 'rail',
 }) {
     const gridRef = useRef(null);
@@ -813,7 +819,9 @@ function GenericIndex({
     // An empty box is worth printing inside the title bar (it holds the bar's
     // right-hand column open) and not worth printing anywhere else.
     const embeddedInfo =
-        !showTitle && (total > 0 || hasHeadings) ? titleInfo : null;
+        !showTitle && showTotal && (total > 0 || hasHeadings)
+            ? titleInfo
+            : null;
 
     // Lay the filter menu out as a horizontal strip rather than a rail. The
     // conditions are written out in `shouldUnderlineTabs`, which is where they

package/src/components/layout/AnchoredMenu.jsx

@@ -0,0 +1,131 @@
+import React, { useCallback, useEffect, useLayoutEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import styles from '../styles/AnchoredMenu.module.scss';
+
+/**
+ * The `⋯` menu on a row, rendered where nothing can clip it.
+ *
+ * Every list in this library's world had the same bug: the menu is
+ * `position: absolute` inside the row, the row is inside a card, and the card
+ * has `overflow: hidden` for its rounded corners — so on the LAST row of a band
+ * the menu was cut off entirely and the button looked like it did nothing. Give
+ * the list a scroll region (`ScrollRegion`) and it gets worse, because a
+ * scrolling ancestor clips too and now every row is the last row.
+ *
+ * There is no arrangement of `overflow` that fixes it, so the menu is not in the
+ * list at all: it is portalled to `document.body` and positioned `fixed` against
+ * the trigger's rectangle. Nothing between it and the viewport can clip it.
+ *
+ * IT CLOSES ON SCROLL rather than following the trigger. A menu that tracks a
+ * row while the list moves under it is more code and a worse idea — by the time
+ * it has travelled two hundred pixels the reader has lost which row it belongs
+ * to. Scrolling means "not that one", so it closes.
+ *
+ * @param {boolean} open       Whether the menu is showing.
+ * @param {Element} anchor     The trigger element to hang it off.
+ * @param {func}    onClose    Called on a click outside, Escape, or a scroll.
+ * @param {'start'|'end'} align  Which edge of the trigger it lines up with.
+ * @param {number}  gap        Space between the trigger and the menu.
+ * @param {string}  label      Accessible name for the menu.
+ */
+const AnchoredMenu = ({
+    open,
+    anchor,
+    onClose,
+    align = 'end',
+    gap = 4,
+    label = 'Actions',
+    className,
+    children,
+}) => {
+    const [position, setPosition] = useState(null);
+
+    const place = useCallback(() => {
+        if (!anchor) return;
+
+        const rect = anchor.getBoundingClientRect();
+
+        setPosition({
+            top: rect.bottom + gap,
+            left: align === 'end' ? null : rect.left,
+            right: align === 'end' ? window.innerWidth - rect.right : null,
+            // Enough room below? Otherwise flip above the trigger. Measured
+            // against a nominal menu height rather than the real one, which is
+            // not known until after it has been placed — and being 20px out on
+            // the decision is invisible, where a menu off the bottom of the
+            // window is not.
+            flip: window.innerHeight - rect.bottom < 180 && rect.top > 180,
+            anchorTop: rect.top,
+        });
+    }, [anchor, align, gap]);
+
+    useLayoutEffect(() => {
+        if (!open) {
+            setPosition(null);
+
+            return undefined;
+        }
+
+        place();
+
+        return undefined;
+    }, [open, place]);
+
+    useEffect(() => {
+        if (!open) return undefined;
+
+        const close = () => onClose?.();
+        const onKeyDown = (event) => {
+            if (event.key === 'Escape') close();
+        };
+
+        // Capture, so a scroll inside a list region closes it too — the event
+        // does not bubble from a scrolling element.
+        window.addEventListener('scroll', close, true);
+        window.addEventListener('resize', close);
+        window.addEventListener('keydown', onKeyDown);
+
+        return () => {
+            window.removeEventListener('scroll', close, true);
+            window.removeEventListener('resize', close);
+            window.removeEventListener('keydown', onKeyDown);
+        };
+    }, [open, onClose]);
+
+    if (!open || !position || typeof document === 'undefined') return null;
+
+    const style = {
+        top: position.flip ? undefined : position.top,
+        bottom: position.flip
+            ? window.innerHeight - position.anchorTop + gap
+            : undefined,
+        left: position.left ?? undefined,
+        right: position.right ?? undefined,
+    };
+
+    return createPortal(
+        <>
+            {/* A full-window hit target behind the menu, so one click anywhere
+                closes it however far the list has been scrolled. */}
+            <button
+                type="button"
+                className={styles.scrim}
+                aria-hidden="true"
+                tabIndex={-1}
+                onClick={() => onClose?.()}
+            />
+            <div
+                className={[styles.menu, className].filter(Boolean).join(' ')}
+                role="menu"
+                aria-label={label}
+                style={style}
+            >
+                {children}
+            </div>
+        </>,
+        document.body
+    );
+};
+
+export default AnchoredMenu;

package/src/components/layout/BandedList.jsx

@@ -0,0 +1,158 @@
+import React, { useRef } from 'react';
+
+import useContainedHeight from './useContainedHeight';
+import styles from '../styles/BandedList.module.scss';
+
+/**
+ * The container a run of bands sits in.
+ *
+ * `stack` is a column of independent bands with air between them. `card` is one
+ * card holding all of them, for `flush` bands — a continuous list broken up by
+ * dividers rather than a set of separate panels.
+ *
+ * `scroll` makes the LIST scroll instead of the page, so the summary strip, the
+ * search box and the view tabs above it stay on the screen while four hundred
+ * rows move underneath. Its height is measured, not declared — see
+ * `useContainedHeight`. Pair it with `sticky` on the bands so their headings
+ * survive the scroll, and remember that a scrolling region CLIPS: a row's `⋯`
+ * popover has to be an `AnchoredMenu`, which portals out of it.
+ *
+ * The same treatment for a list this component does not draw — an embedded data
+ * grid, say — is `ScrollRegion`, which is the identical mechanism without the
+ * bands.
+ *
+ * @param {'stack'|'card'} variant
+ * @param {boolean} scroll     Contain the scrolling to the rows.
+ * @param {number}  gutter     Space to leave under the region, in pixels.
+ * @param {*}       remeasure  Anything whose change alters what is above it.
+ */
+const BandedList = ({
+    variant = 'stack',
+    scroll = false,
+    gutter = 24,
+    remeasure = null,
+    className,
+    style,
+    children,
+    ...rest
+}) => {
+    const ref = useRef(null);
+    const height = useContainedHeight(ref, gutter, remeasure, scroll);
+
+    return (
+        <div
+            ref={ref}
+            className={[
+                styles.board,
+                variant === 'card' ? styles.boardCard : null,
+                scroll ? styles.scroll : null,
+                className,
+            ]
+                .filter(Boolean)
+                .join(' ')}
+            style={
+                scroll && height !== null ? { ...style, maxHeight: height } : style
+            }
+            {...rest}
+        >
+            {children}
+        </div>
+    );
+};
+
+const TONES = {
+    danger: styles.toneDanger,
+    warn: styles.toneWarn,
+    neutral: styles.toneNeutral,
+    quiet: styles.toneQuiet,
+};
+
+/**
+ * One band: a heading with a count, a note or a subtotal on the right, an
+ * urgency on the left edge, and the host's own rows underneath.
+ *
+ * `collapseWhenEmpty` is the behaviour worth knowing about. A board built from a
+ * FIXED list of bands — overdue, this week, this month, later — has to be able
+ * to draw only the ones that have something in them, or a quiet week renders as
+ * five headings over nothing. Pass `count` and the band takes itself off the
+ * page at zero. A band that genuinely wants to say "none" sets
+ * `collapseWhenEmpty={false}` and puts the sentence in its children.
+ *
+ * @param {'card'|'plain'|'flush'} variant  See BandedList.module.scss.
+ * @param {'danger'|'warn'|'neutral'|'quiet'} tone   The left edge. `card` only.
+ * @param {node}    title             The heading.
+ * @param {number}  count             Drawn beside the heading, and the thing
+ *                                    `collapseWhenEmpty` reads.
+ * @param {node}    meta              Right-hand slot — a subtotal, a chip.
+ * @param {node}    note              Right-hand small print, after `meta`.
+ * @param {boolean} sticky            Pins the heading while its rows scroll.
+ * @param {string}  titleAs           Element for the heading. `h2` by default;
+ *                                    a letter divider in a filing drawer is not
+ *                                    a heading and should say `span`.
+ */
+const Band = ({
+    variant = 'card',
+    tone = 'neutral',
+    title,
+    count,
+    meta,
+    note,
+    sticky = false,
+    collapseWhenEmpty = true,
+    titleAs: TitleElement = 'h2',
+    className,
+    headClassName,
+    children,
+    ...rest
+}) => {
+    if (collapseWhenEmpty && count === 0) return null;
+
+    const hasHead =
+        title !== undefined ||
+        count !== undefined ||
+        meta !== undefined ||
+        note !== undefined;
+
+    return (
+        <section
+            className={[styles.band, styles[variant], TONES[tone], className]
+                .filter(Boolean)
+                .join(' ')}
+            {...rest}
+        >
+            {hasHead && (
+                <header
+                    className={[
+                        styles.head,
+                        sticky ? styles.headSticky : null,
+                        headClassName,
+                    ]
+                        .filter(Boolean)
+                        .join(' ')}
+                >
+                    <TitleElement className={styles.title}>
+                        {title}
+                        {count !== undefined && count !== null && (
+                            <span className={styles.count}>{count}</span>
+                        )}
+                    </TitleElement>
+
+                    {(meta !== undefined && meta !== null) ||
+                    (note !== undefined && note !== null) ? (
+                        <span className={styles.meta}>
+                            {meta}
+                            {note ? (
+                                <span className={styles.note}>{note}</span>
+                            ) : null}
+                        </span>
+                    ) : null}
+                </header>
+            )}
+
+            {children}
+        </section>
+    );
+};
+
+export { Band };
+export default BandedList;

package/src/components/layout/FactsBand.jsx

@@ -0,0 +1,150 @@
+import React from 'react';
+
+import styles from '../styles/FactsBand.module.scss';
+
+/**
+ * The band of facts that sits under a record's title and stays there.
+ *
+ * A detail screen built out of tabs has one structural problem: the answer to
+ * "who do I ring / is anything on fire here" is on the fourth tab, and opening
+ * any other tab takes it off the screen. The band is the fix — the handful of
+ * facts somebody opened the record FOR, above the strip, unaffected by which tab
+ * is showing.
+ *
+ * IT SHOULD ALWAYS RENDER ITS CONTAINER, including while loading and when the
+ * fetch fails — hence `state`. A band that returns null makes the tab strip jump
+ * by 70px on every page load, and in a layout that orders its children by
+ * position (the CRM's customer record does exactly this) a missing band promotes
+ * the tab strip into the title's place and draws the page upside down.
+ *
+ * @param {node}   state       Renders one full-width sentence instead of the
+ *                             cells — "Loading…", or why it could not load.
+ * @param {string} minWidth    Narrowest a cell may get before the grid drops a
+ *                             column. Writes `--vs-facts-min` inline; pass this
+ *                             OR set the property from a stylesheet, not both.
+ * @param {string} columns     A whole `grid-template-columns` value, for what
+ *                             auto-fit cannot express. Writes
+ *                             `--vs-facts-columns`.
+ */
+const FactsBand = ({
+    state,
+    minWidth,
+    columns,
+    className,
+    style,
+    children,
+    ...rest
+}) => {
+    const vars = { ...style };
+
+    if (minWidth) vars['--vs-facts-min'] = minWidth;
+    if (columns) vars['--vs-facts-columns'] = columns;
+
+    return (
+        <div
+            className={[styles.band, className].filter(Boolean).join(' ')}
+            style={vars}
+            {...rest}
+        >
+            {state !== undefined && state !== null ? (
+                <span className={styles.state}>{state}</span>
+            ) : (
+                children
+            )}
+        </div>
+    );
+};
+
+const TONES = {
+    accent: styles.toneAccent,
+    warn: styles.toneWarn,
+    danger: styles.toneDanger,
+};
+
+/**
+ * One cell of the band.
+ *
+ * `value` and `figure` are the two ways a fact reads, and a cell takes one or
+ * the other: a name, a suburb or a phone number is TEXT (clipped, semibold, and
+ * a link when `href` is given), while a count is a FIGURE (large, tabular, so
+ * the eye finds the numbers across the row). Passing both is legal and draws
+ * both, which is occasionally what a cell wants; passing `children` replaces the
+ * lot for the cells that are genuinely bespoke.
+ *
+ * @param {node}   label     Small caps over the fact.
+ * @param {node}   value     Read as text. Becomes an `<a>` when `href` is set.
+ * @param {node}   figure    Read as a number.
+ * @param {node}   note      The line under it.
+ * @param {'accent'|'warn'|'danger'} tone  Colours the figure or the value.
+ * @param {string} href      Makes the value a link — `tel:`, `mailto:`, a route.
+ */
+const Fact = ({
+    label,
+    value,
+    figure,
+    note,
+    tone,
+    href,
+    className,
+    valueClassName,
+    noteClassName,
+    children,
+    ...rest
+}) => {
+    const ValueElement = href ? 'a' : 'span';
+
+    return (
+        <span
+            className={[styles.cell, className].filter(Boolean).join(' ')}
+            {...rest}
+        >
+            {label !== undefined && label !== null && (
+                <span className={styles.label}>{label}</span>
+            )}
+
+            {children ?? (
+                <>
+                    {figure !== undefined && figure !== null && (
+                        <span
+                            className={[styles.figure, TONES[tone], valueClassName]
+                                .filter(Boolean)
+                                .join(' ')}
+                        >
+                            {figure}
+                        </span>
+                    )}
+
+                    {value !== undefined && value !== null && (
+                        <ValueElement
+                            className={[
+                                styles.value,
+                                figure === undefined || figure === null
+                                    ? TONES[tone]
+                                    : null,
+                                valueClassName,
+                            ]
+                                .filter(Boolean)
+                                .join(' ')}
+                            {...(href ? { href } : {})}
+                        >
+                            {value}
+                        </ValueElement>
+                    )}
+
+                    {note !== undefined && note !== null && note !== '' && (
+                        <span
+                            className={[styles.note, noteClassName]
+                                .filter(Boolean)
+                                .join(' ')}
+                        >
+                            {note}
+                        </span>
+                    )}
+                </>
+            )}
+        </span>
+    );
+};
+
+export { Fact };
+export default FactsBand;

package/src/components/layout/PageHeader.jsx

@@ -0,0 +1,90 @@
+import React from 'react';
+
+import styles from '../styles/PageHeader.module.scss';
+
+const ALIGN = {
+    center: styles.alignCenter,
+    start: styles.alignStart,
+    end: styles.alignEnd,
+};
+
+/**
+ * The row at the top of a screen: what this page is, and what you can do to it.
+ *
+ * Six screens in the CRM had written this out by hand and had already drifted —
+ * three alignments, two title sizes, two different paddings, and one of them was
+ * missing the `nav { min-width: 0 }` that stops a breadcrumb shoving the buttons
+ * off the row. It is one component now.
+ *
+ * The left side takes either the title/subtitle pair or `children`, and pages
+ * that lead with a breadcrumb pass it as `children`. The title's size is a token
+ * (`--vs-header-title-size`) rather than a prop: a dashboard that wants a 1.4rem
+ * heading wants it on every one of its screens, which is a stylesheet decision,
+ * not a per-call one.
+ *
+ * @param {node}    title      Rendered as the page's `h1`.
+ * @param {node}    subtitle   One line under it.
+ * @param {node}    back       Rendered above the title — a "‹ All clients" link.
+ * @param {node}    actions    Hard right. Buttons, a picker, a refresh.
+ * @param {node}    children   Replaces the title/subtitle block outright.
+ * @param {'center'|'start'|'end'} align  How the two halves line up.
+ * @param {boolean} gutter     The quarter-rem of air a breadcrumb sits in.
+ * @param {boolean} sticky     Pins the row while the page scrolls.
+ * @param {string}  titleAs    Element for the title. `h1` by default — pass
+ *                             something else on a page that already has one.
+ */
+const PageHeader = ({
+    title,
+    subtitle,
+    back,
+    actions,
+    align = 'center',
+    gutter = false,
+    sticky = false,
+    titleAs: TitleElement = 'h1',
+    className,
+    mainClassName,
+    actionsClassName,
+    children,
+    ...rest
+}) => (
+    <div
+        className={[
+            styles.header,
+            ALIGN[align],
+            gutter ? styles.gutter : null,
+            sticky ? styles.sticky : null,
+            className,
+        ]
+            .filter(Boolean)
+            .join(' ')}
+        {...rest}
+    >
+        <div className={[styles.main, mainClassName].filter(Boolean).join(' ')}>
+            {back}
+
+            {children ?? (
+                <>
+                    {title !== undefined && title !== null && (
+                        <TitleElement className={styles.title}>{title}</TitleElement>
+                    )}
+                    {subtitle !== undefined && subtitle !== null && (
+                        <p className={styles.subtitle}>{subtitle}</p>
+                    )}
+                </>
+            )}
+        </div>
+
+        {actions ? (
+            <div
+                className={[styles.actions, actionsClassName]
+                    .filter(Boolean)
+                    .join(' ')}
+            >
+                {actions}
+            </div>
+        ) : null}
+    </div>
+);
+
+export default PageHeader;

package/src/components/layout/ScrollRegion.jsx

@@ -0,0 +1,53 @@
+import React, { useRef } from 'react';
+
+import useContainedHeight from './useContainedHeight';
+import styles from '../styles/ScrollRegion.module.scss';
+
+/**
+ * A region that scrolls so the page does not.
+ *
+ * Wrap the LIST half of a screen whose top half is chrome — a summary strip, a
+ * search box, a row of view tabs — and the chrome stays on the screen while the
+ * rows move under it. On the tablet this CRM is driven on that is the whole
+ * difference between filtering a list and hunting for the filter.
+ *
+ * The height is measured rather than declared; see `useContainedHeight` for why
+ * a `calc(100vh - 22rem)` is wrong on half the states of a real page.
+ *
+ * TWO THINGS IT DOES NOT DO, both on purpose:
+ *
+ *   It does not set `overscroll-behavior`. Trapping the scroll at the end of the
+ *   list is what makes a long page feel broken on a touchscreen; when this
+ *   region has finished, the page should carry on.
+ *
+ *   It does not clip popovers for you. A `⋯` menu inside a scroll region is
+ *   inside a clipping ancestor and WILL be cut off — use `AnchoredMenu`, which
+ *   renders through a portal and is not affected.
+ *
+ * @param {number} gutter  Space to leave beneath the region, in pixels.
+ * @param {*}      remeasure  Anything whose change alters what is above it.
+ */
+const ScrollRegion = ({
+    gutter = 24,
+    remeasure = null,
+    className,
+    style,
+    children,
+    ...rest
+}) => {
+    const ref = useRef(null);
+    const height = useContainedHeight(ref, gutter, remeasure);
+
+    return (
+        <div
+            ref={ref}
+            className={[styles.region, className].filter(Boolean).join(' ')}
+            style={height === null ? style : { ...style, maxHeight: height }}
+            {...rest}
+        >
+            {children}
+        </div>
+    );
+};
+
+export default ScrollRegion;