@visns-studio/visns-components 6.20.1 → 6.23.0

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;

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;