@visns-studio/visns-components 6.20.0 → 6.21.0

package/src/components/layout/StatStrip.jsx

@@ -0,0 +1,170 @@
+import React from 'react';
+
+import styles from '../styles/StatStrip.module.scss';
+
+/**
+ * A row of labelled figures about the set below it.
+ *
+ * Five screens in the CRM had each written this markup out by hand — support
+ * blocks, subscriptions, contacts, the client book and the Zoom dashboard — and
+ * they had already drifted: two of them weighted the label, one of them coloured
+ * the figure, and the padding was off by a hundredth of a rem in three places.
+ * It is one component now, in two variants (see StatStrip.module.scss), because
+ * the difference between "one card of hairline-separated cells" and "separate
+ * tiles" is a real design decision each of those pages made on purpose.
+ *
+ * What it deliberately does NOT do is fetch, format or decide. The figures
+ * arrive formatted; whether a number is alarming is the page's judgement, and it
+ * says so with `tone` / `emphasis`. That is what keeps this usable by a screen
+ * whose numbers are hours, one whose numbers are money and one whose numbers are
+ * counts of broken things.
+ *
+ * @param {'joined'|'tiles'} variant  Hairline grid, or separate tiles.
+ * @param {string} minWidth           Narrowest a column may get before the grid
+ *                                    drops one, e.g. `'10rem'`. Writes
+ *                                    `--vs-stat-min` inline — so pass this OR
+ *                                    set the property from your own stylesheet
+ *                                    (which is what you want if the value
+ *                                    changes at a breakpoint), never both.
+ * @param {string} columns            A whole `grid-template-columns` value,
+ *                                    for the track lists auto-fit cannot say.
+ *                                    Writes `--vs-stat-columns`.
+ */
+const StatStrip = ({
+    variant = 'joined',
+    minWidth,
+    columns,
+    className,
+    style,
+    children,
+    ...rest
+}) => {
+    const vars = { ...style };
+
+    if (minWidth) vars['--vs-stat-min'] = minWidth;
+    if (columns) vars['--vs-stat-columns'] = columns;
+
+    return (
+        <div
+            className={[styles.strip, styles[variant], className]
+                .filter(Boolean)
+                .join(' ')}
+            style={vars}
+            {...rest}
+        >
+            {children}
+        </div>
+    );
+};
+
+const TONES = {
+    accent: styles.toneAccent,
+    heading: styles.toneHeading,
+    warn: styles.toneWarn,
+    danger: styles.toneDanger,
+};
+
+const EMPHASIS = {
+    warn: styles.emphasisWarn,
+    danger: styles.emphasisDanger,
+};
+
+/**
+ * One figure: a label, a value, and a line of small print under it.
+ *
+ * Both of the shapes the CRM screens use are here, and they are the same three
+ * slots read two ways — "count + note" (`142` / *across 12 blocks*) and "value +
+ * share" (`$2,410` `/mo` / *$28,920 a year*). The unit is separate from the
+ * value so it can stay at small print rather than being sized up with the
+ * figure.
+ *
+ * `onClick` (or `href`) makes the whole cell the target rather than putting a
+ * link inside it — on the tablet this CRM is driven on, that is the difference
+ * between one tap and aiming at a word.
+ *
+ * @param {node}   label     Small caps over the figure.
+ * @param {node}   value     The figure itself, already formatted.
+ * @param {node}   unit      Small print immediately after the value.
+ * @param {node}   note      The line under it.
+ * @param {'accent'|'heading'|'warn'|'danger'} tone
+ *                           Colours the FIGURE. Pass it only while the figure
+ *                           is worth colouring: a permanently red tile is a
+ *                           tile nobody reads.
+ * @param {'warn'|'danger'}  emphasis
+ *                           Skins the whole tile. `tiles` variant only.
+ * @param {'warn'} noteTone  Weights the note instead of the figure.
+ */
+const Stat = ({
+    label,
+    value,
+    unit,
+    note,
+    tone,
+    emphasis,
+    noteTone,
+    onClick,
+    href,
+    className,
+    valueClassName,
+    noteClassName,
+    children,
+    ...rest
+}) => {
+    const interactive = Boolean(onClick || href);
+    const Element = href ? 'a' : onClick ? 'button' : 'div';
+
+    const body = children ?? (
+        <>
+            {label !== undefined && label !== null && (
+                <span className={styles.label}>{label}</span>
+            )}
+
+            {value !== undefined && value !== null && (
+                <span
+                    className={[styles.value, TONES[tone], valueClassName]
+                        .filter(Boolean)
+                        .join(' ')}
+                >
+                    {value}
+                    {unit ? <span className={styles.unit}>{unit}</span> : null}
+                </span>
+            )}
+
+            {note !== undefined && note !== null && note !== '' && (
+                <span
+                    className={[
+                        styles.note,
+                        noteTone === 'warn' ? styles.noteWarn : null,
+                        noteClassName,
+                    ]
+                        .filter(Boolean)
+                        .join(' ')}
+                >
+                    {note}
+                </span>
+            )}
+        </>
+    );
+
+    return (
+        <Element
+            className={[
+                styles.stat,
+                interactive ? styles.interactive : null,
+                EMPHASIS[emphasis],
+                className,
+            ]
+                .filter(Boolean)
+                .join(' ')}
+            {...(Element === 'button' ? { type: 'button' } : {})}
+            {...(href ? { href } : {})}
+            {...(onClick ? { onClick } : {})}
+            {...rest}
+        >
+            {body}
+        </Element>
+    );
+};
+
+export { Stat };
+export default StatStrip;

package/src/components/layout/useContainedHeight.js

@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useState } from 'react';
+
+/**
+ * "Be as tall as whatever is left of the window, and scroll inside that."
+ *
+ * The problem it solves is not scrolling, it is LOSING THE CHROME. A list of
+ * four hundred clients scrolls the whole document, which takes the summary
+ * strip, the search box and the view tabs off the top of the screen — so
+ * finding a name and then narrowing the search means scrolling back up to
+ * controls that were in front of you a moment ago. Give the rows their own
+ * scroll region and everything above them stays put.
+ *
+ * WHY MEASURED RATHER THAN A CONSTANT. The obvious implementation is
+ * `max-height: calc(100vh - 22rem)` with the 22rem counted off the design. It
+ * is wrong on half the states of a real page: the strip has not loaded yet, a
+ * truncation notice appeared at a hundred rows, the header wrapped to two lines
+ * on a tablet. So the height is read from where the region actually starts —
+ * `getBoundingClientRect().top` — and recomputed whenever the window resizes or
+ * anything above it changes size.
+ *
+ * The `ResizeObserver` watches the region's PARENT rather than the region
+ * itself: the region's own height is the thing being set, and observing it
+ * would be a loop. What is wanted is "did the chrome above me move?", and the
+ * parent growing is the signal for that.
+ *
+ * Returns `null` until the first measurement, which is deliberate — a region
+ * rendered with no max-height for one frame is a page that is briefly too long,
+ * where one rendered at a guessed height is a page that visibly jumps.
+ *
+ * @param {object}  ref      Ref on the scrolling element.
+ * @param {number}  gutter   Space to leave under it, in pixels.
+ * @param {*}       deps     Anything that changes what is above it.
+ * @param {boolean} enabled  False leaves the height null and installs no
+ *                           listeners — for a component where the containment
+ *                           is opt-in and the hook still has to be called
+ *                           unconditionally.
+ */
+const useContainedHeight = (ref, gutter = 24, deps = null, enabled = true) => {
+    const [height, setHeight] = useState(null);
+
+    const measure = useCallback(() => {
+        const node = ref.current;
+
+        if (!enabled || !node || typeof window === 'undefined') return;
+
+        const top = node.getBoundingClientRect().top;
+        const available = window.innerHeight - top - gutter;
+
+        // A floor rather than a clamp to zero: on a short window the region
+        // still has to be usable, and 200px is about four rows.
+        setHeight(Math.max(available, 200));
+    }, [ref, gutter, enabled]);
+
+    useEffect(() => {
+        if (!enabled) return undefined;
+
+        measure();
+
+        window.addEventListener('resize', measure);
+
+        // Orientation changes on an iPad settle a beat after the event.
+        const settle = setTimeout(measure, 200);
+
+        let observer = null;
+
+        if (typeof ResizeObserver !== 'undefined' && ref.current?.parentElement) {
+            observer = new ResizeObserver(measure);
+            observer.observe(ref.current.parentElement);
+        }
+
+        return () => {
+            window.removeEventListener('resize', measure);
+            clearTimeout(settle);
+            if (observer) observer.disconnect();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [measure, deps, enabled]);
+
+    return height;
+};
+
+export default useContainedHeight;

package/src/components/navigation/TabStrip.jsx

@@ -0,0 +1,156 @@
+import React, { useCallback } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+import styles from '../styles/TabStrip.module.scss';
+
+/**
+ * react-router's search params, if there is a Router.
+ *
+ * Same shape and the same reasoning as `auth/useOptionalRouter`: the hook is
+ * called unconditionally on every render and only its throw is swallowed, which
+ * is what keeps this legal under the rules of hooks — whether a Router is above
+ * a component is fixed for that component's lifetime, so React never sees the
+ * hook count change.
+ *
+ * A strip used outside a Router simply cannot be URL-driven, and falls back to
+ * being controlled.
+ */
+const useOptionalSearchParams = () => {
+    try {
+        return useSearchParams();
+    } catch (error) {
+        // No Router above us. Expected wherever this is mounted outside an SPA.
+        return [null, null];
+    }
+};
+
+/**
+ * The underline tabs, driven either by the URL or by the caller.
+ *
+ * TWO MODES, and which one a page wants depends on whether the tab is a place.
+ *
+ *   CONTROLLED — pass `active` and `onChange`. The right answer when the tab is
+ *   a filter over the same page ("Active / Retired / All"): those are not
+ *   locations, and putting them in the URL invites somebody to bookmark a view
+ *   of a list rather than the list.
+ *
+ *   URL-DRIVEN — pass `param` (usually `'tab'`) and no `active`. The right
+ *   answer when the tab is a SECTION of a record: a deep link, a refresh and a
+ *   shared link all have to land in the same place. `replace` defaults to true
+ *   so five tab clicks do not become five back-button steps through a page
+ *   nobody ever left; a page whose tabs genuinely are separate destinations can
+ *   turn it off.
+ *
+ * Real `<button>`s in a tablist rather than links, in both modes: even when the
+ * tab is reflected in the URL, switching it is a state change rather than a
+ * navigation, and a router push per click fills the back button with noise.
+ *
+ * @param {Array}  tabs      `[{key, label, badge, badgeTone, disabled}]`.
+ * @param {string} active    Controlled mode: the current key.
+ * @param {func}   onChange  Called with the key. Fires in URL mode too, so a
+ *                           page can invalidate a cache on the way past.
+ * @param {string} param     URL mode: the search param that owns the tab.
+ * @param {bool}   replace   URL mode: replace rather than push. Default true.
+ * @param {string} fallback  What an unrecognised (or absent) param means.
+ *                           Defaults to the first tab.
+ * @param {'quiet'|'danger'} badgeTone  Default tone for every badge.
+ */
+const TabStrip = ({
+    tabs = [],
+    active,
+    onChange,
+    param,
+    replace = true,
+    fallback,
+    ariaLabel = 'Sections',
+    badgeTone = 'quiet',
+    className,
+    tabClassName,
+    ...rest
+}) => {
+    const [searchParams, setSearchParams] = useOptionalSearchParams();
+
+    const urlDriven = Boolean(param) && searchParams !== null && active === undefined;
+
+    const known = (key) => tabs.some((tab) => tab.key === key);
+    const defaultKey = fallback ?? tabs[0]?.key;
+
+    let current = active;
+
+    if (urlDriven) {
+        const requested = searchParams.get(param);
+
+        current = known(requested) ? requested : defaultKey;
+    }
+
+    const select = useCallback(
+        (key) => {
+            if (urlDriven) {
+                setSearchParams(
+                    (params) => {
+                        const next = new URLSearchParams(params);
+
+                        next.set(param, key);
+
+                        return next;
+                    },
+                    { replace }
+                );
+            }
+
+            if (onChange) onChange(key);
+        },
+        [urlDriven, setSearchParams, param, replace, onChange]
+    );
+
+    if (tabs.length === 0) return null;
+
+    return (
+        <div
+            className={[styles.strip, className].filter(Boolean).join(' ')}
+            role="tablist"
+            aria-label={ariaLabel}
+            {...rest}
+        >
+            {tabs.map((tab) => {
+                const selected = current === tab.key;
+                const tone = tab.badgeTone ?? badgeTone;
+
+                return (
+                    <button
+                        key={tab.key}
+                        type="button"
+                        role="tab"
+                        aria-selected={selected}
+                        disabled={tab.disabled}
+                        className={[
+                            styles.tab,
+                            selected ? styles.active : null,
+                            tabClassName,
+                        ]
+                            .filter(Boolean)
+                            .join(' ')}
+                        onClick={() => select(tab.key)}
+                    >
+                        {tab.label}
+
+                        {tab.badge ? (
+                            <span
+                                className={[
+                                    styles.badge,
+                                    tone === 'danger'
+                                        ? styles.badgeDanger
+                                        : styles.badgeQuiet,
+                                ].join(' ')}
+                            >
+                                {tab.badge}
+                            </span>
+                        ) : null}
+                    </button>
+                );
+            })}
+        </div>
+    );
+};
+
+export default TabStrip;

package/src/components/sms/smsHelpers.js

@@ -157,6 +157,61 @@ export const toE164 = (value, countryCode = '61') => {
     return null;
 };
 
+/* ------------------------------------------------------- dialling a number */
+
+/**
+ * A number as a person would write it, or '' when there is nothing to show.
+ *
+ * A thin wrapper on `normaliseNumberForDisplay`, and the reason it exists is the
+ * empty case: the formatter returns whatever it was given when it cannot parse
+ * it, including `undefined`, and a display slot wants a string it can render.
+ *
+ * Use THIS rather than the data grid's `renderPhoneColumn` for anything that is
+ * not a grid cell. The grid's formatter collapses `+61` through the guard
+ * `/^61[2-9]\d{8}$/`, which excludes `4` and therefore silently fails to format
+ * the one case a contact screen cares about most — a stored `+61412345678`
+ * mobile falls through to its generic branch and renders unformatted.
+ */
+export const displayNumber = (value) => normaliseNumberForDisplay(value) || '';
+
+/**
+ * The `href` for a phone number, or null when it is not dialable.
+ *
+ * `tel:` wants an unambiguous number, not a pretty one: a tablet handing
+ * `(08) 9375 2549` to a dialler is handing it a string with brackets in it. So
+ * E.164 is preferred, and `toE164` produces it.
+ *
+ * THE 13 / 1300 / 1800 CAVEAT. `toE164` answers null for the Australian service
+ * prefixes, because they genuinely have no country-code form. They are still
+ * perfectly dialable, so rather than drop the link they fall back to the bare
+ * digits, which is what a handset expects for them.
+ *
+ * Anything with no digits at all — "ask reception", and it IS in this column in
+ * real data — gets no link, because an anchor that dials nothing is worse than
+ * plain text.
+ */
+export const telHref = (value) => {
+    const e164 = toE164(value);
+
+    if (e164) return `tel:${e164}`;
+
+    const digits = String(value ?? '').replace(/[^\d]/g, '');
+
+    return /^1[38]00\d{6}$|^13\d{4}$/.test(digits) ? `tel:${digits}` : null;
+};
+
+/**
+ * As above, for the text action on a mobile.
+ *
+ * No service-prefix fallback here, deliberately: 13/1300/1800 numbers cannot
+ * receive an SMS at all, so a link to one is a promise that would be broken.
+ */
+export const smsHref = (value) => {
+    const e164 = toE164(value);
+
+    return e164 ? `sms:${e164}` : null;
+};
+
 /* ----------------------------------------------------------------- segments */
 
 /**
@@ -1159,6 +1214,7 @@ export default {
     dayLabel,
     describeRecipient,
     describeTransport,
+    displayNumber,
     fillTemplate,
     groupMessagesByDay,
     initialsFor,
@@ -1174,9 +1230,11 @@ export default {
     RECIPIENT_HINTS,
     relativeTime,
     segmentCount,
+    smsHref,
     splitPersonName,
     statusLabel,
     sumUnread,
+    telHref,
     threadDisplayName,
     threadIdFromSearch,
     threadSubtitle,

package/src/components/styles/AnchoredMenu.module.scss

@@ -0,0 +1,43 @@
+@use 'surface' as *;
+
+/**
+ * AnchoredMenu — the row menu, portalled out of everything that would clip it.
+ *
+ * It renders into `document.body`, which means it is OUTSIDE the page's own
+ * token block: a `--vs-line` declared on `.page` does not inherit to a sibling
+ * of `<div id="app">`. So this is the one module in the set that reads the app's
+ * tokens directly and offers no page-level override — a menu is neutral chrome
+ * anyway, and a per-page menu skin was never a thing anybody wanted.
+ *
+ * `z-index` sits above a page's own furniture and below the modal layer (1051+
+ * in this library's stack), because a menu must not float over the sheet a
+ * click on it opens.
+ */
+
+.scrim {
+    position: fixed;
+    inset: 0;
+    z-index: 900;
+    padding: 0;
+    background: transparent;
+    border: 0;
+    cursor: default;
+}
+
+.menu {
+    @include surface-tokens;
+
+    position: fixed;
+    z-index: 901;
+    display: flex;
+    flex-direction: column;
+    min-width: 11rem;
+    max-width: min(20rem, calc(100vw - 1rem));
+    padding: 4px;
+    background: var(--pr-surface);
+    border: 1px solid var(--pr-line);
+    border-radius: var(--btn-br, 5px);
+    box-shadow:
+        0 1px 2px rgb(0 0 0 / 8%),
+        0 8px 24px -12px rgb(0 0 0 / 35%);
+}