@visns-studio/visns-components 6.20.1 → 6.21.0

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

@@ -0,0 +1,278 @@
+@use 'surface' as *;
+
+/**
+ * BandedList — sections with a heading, a count, and an urgency on the edge.
+ *
+ * THE ONE IDEA THIS FILE CARRIES is that urgency is a property of the SECTION,
+ * not of the row. Each band gets a coloured left edge and a heading that says
+ * what its contents mean; the rows inside stay quiet and uniform. The
+ * alternative — colouring every overdue row red — turns a book with forty lapsed
+ * renewals into a wall of alarm nobody can read.
+ *
+ * The rows themselves are the host's. This draws the scaffolding and nothing
+ * else: a support block card, a subscription line and a client row have almost
+ * nothing in common, and a component that tried to render all three would be a
+ * config format rather than a primitive.
+ *
+ * Three variants, one per shape the CRM's screens actually draw:
+ *
+ *   `card`   a card per band, urgency on its left border. For bands that are
+ *            independent of each other — this week's renewals and last month's.
+ *   `plain`  no card at all: a bare heading over whatever follows. For a page
+ *            whose rows are already cards and would otherwise be cards inside
+ *            cards.
+ *   `flush`  no card of its own, sitting inside ONE shared card with its
+ *            siblings, heading sticky. For a continuous list broken up by
+ *            dividers — the A–Z tabs in a filing drawer.
+ */
+
+/* -------------------------------------------------------------------------- */
+/* the container                                                              */
+/* -------------------------------------------------------------------------- */
+
+.board {
+    @include surface-tokens;
+
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacing-md, 1rem);
+}
+
+/* ONE card holding every band, rather than a card per band — the container for
+   `flush`. A drawer of clients is one drawer; breaking it into twenty-six panels
+   would put a shadow and a radius between D and E for no reason. */
+.boardCard {
+    display: block;
+    background: var(--pr-surface);
+    border: 1px solid var(--pr-line);
+    border-radius: var(--pr-radius);
+    box-shadow: var(--pr-shadow);
+}
+
+/* -------------------------------------------------------------------------- */
+/* contained scrolling                                                        */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The rows scroll, the page does not.
+ *
+ * A list of four hundred clients scrolls the whole document, which takes the
+ * summary strip, the search box and the view tabs off the screen — so finding a
+ * name and then filtering it means scrolling back up to controls that used to be
+ * in front of you. The rows get their own scroll region instead and the chrome
+ * above them stays put.
+ *
+ * The height is set INLINE by `useContainedHeight`, measured from where the
+ * region actually starts rather than guessed from a stack of constants — the
+ * chrome above it changes height (a summary that has not loaded, a truncation
+ * notice that appears at a hundred rows) and a hard-coded offset is wrong on
+ * half the states of the page.
+ *
+ * `overscroll-behavior` is deliberately LEFT ALONE. Trapping the scroll at the
+ * end of the list is the behaviour that makes a long page feel broken on an
+ * iPad; when this region is done scrolling, the page should carry on.
+ */
+.scroll {
+    overflow: auto;
+    /* Narrow screens scroll their overflow HERE rather than tipping the whole
+       document sideways. */
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
+}
+
+/* -------------------------------------------------------------------------- */
+/* one band                                                                   */
+/* -------------------------------------------------------------------------- */
+
+.band {
+    @include surface-tokens;
+
+    display: block;
+}
+
+/* NOT `overflow: hidden`, however much the rounded corners want it.
+ *
+ * A row inside a band carries a `⋯` menu, and a clipping ancestor eats it — on
+ * the last row of a band the popover was cut off entirely and the menu looked
+ * like a button that did nothing. Corners are handled by rounding the heading
+ * and the last row instead (see `.head` below, and the host's own last-row
+ * rule), which costs two rules and keeps every popover visible. */
+.card {
+    background: var(--pr-surface);
+    border: 1px solid var(--pr-line);
+    /* Drawn at full width in the line colour and recoloured by the tone, so a
+       band with no urgency is not 3px narrower than one that has some. */
+    border-left: 3px solid var(--pr-line);
+    border-radius: var(--pr-radius);
+}
+
+.plain {
+    display: flex;
+    flex-direction: column;
+    gap: 0.6rem;
+}
+
+.toneDanger.card {
+    border-left-color: var(--pr-danger);
+}
+
+.toneWarn.card {
+    border-left-color: var(--pr-warn);
+}
+
+.toneNeutral.card {
+    border-left-color: var(--pr-accent);
+}
+
+.toneQuiet.card {
+    border-left-color: color-mix(in srgb, var(--pr-ink) 18%, transparent);
+}
+
+/* -------------------------------------------------------------------------- */
+/* the heading                                                                */
+/* -------------------------------------------------------------------------- */
+
+.head {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    align-items: baseline;
+    justify-content: space-between;
+}
+
+.card > .head,
+.flush > .head {
+    padding: 0.7rem var(--spacing-md, 1rem);
+    background: var(--pr-quiet);
+    border-bottom: 1px solid var(--pr-line);
+}
+
+/* The corner the card no longer clips for itself. Inset by the border width, so
+   the tinted heading meets the border rather than showing a hairline of page
+   behind it. */
+.card > .head {
+    border-radius: calc(var(--pr-radius) - 1px) calc(var(--pr-radius) - 1px) 0 0;
+}
+
+.boardCard > .flush:first-child > .head {
+    border-radius: calc(var(--pr-radius) - 1px) calc(var(--pr-radius) - 1px) 0 0;
+}
+
+/* Flush bands share one card, so the divider between two of them is a rule on
+   the second one's heading — there is no card edge to do it for them. */
+.flush + .flush > .head {
+    border-top: 1px solid var(--pr-line);
+}
+
+/* A `plain` heading is type on the page ground: no slab, no rule, and the
+   right-hand note pushed out by the count rather than by a space-between that
+   has nothing to push against. */
+.plain > .head {
+    gap: 0.5rem;
+    padding: 0 0.25rem;
+}
+
+/* Sticky is opt-in, and it is the whole point of a flush band: the heading's
+   job is to tell you where you are once you have scrolled past the top of its
+   group. */
+.headSticky {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+}
+
+/* A sticky heading has to be OPAQUE or the rows read straight through it, and
+   `--pr-quiet` is usually a translucent mix — it is a tint meant to be laid over
+   a surface, not a colour. Layering it over `--pr-surface` as two backgrounds
+   composites the same shade with nothing showing through. */
+.card > .headSticky,
+.flush > .headSticky {
+    background:
+        linear-gradient(var(--pr-quiet), var(--pr-quiet)),
+        var(--pr-surface);
+}
+
+/* A plain heading has no slab of its own, so it borrows the PAGE ground — not
+   the card surface, which would draw a white bar across a warm page. */
+.plain > .headSticky {
+    padding: 0.35rem 0.25rem;
+    background: var(--pr-page);
+}
+
+.flush > .head {
+    padding: 0.4rem var(--spacing-md, 1rem);
+}
+
+.title {
+    display: flex;
+    gap: 0.5rem;
+    align-items: center;
+    margin: 0;
+    color: var(--pr-heading);
+    font-size: 0.95rem;
+    font-weight: var(--font-weight-semibold, 600);
+}
+
+/* A plain heading is small caps on the page ground, and it takes the page's own
+   ink rather than the heading colour — a run of five of them in the brand green
+   reads as five separate pages. */
+.plain > .head > .title {
+    gap: 0.5rem;
+    align-items: baseline;
+    color: inherit;
+    font-size: var(--font-size-sm, 0.8125rem);
+    font-weight: 700;
+    letter-spacing: 0.02em;
+    text-transform: uppercase;
+}
+
+.flush > .head > .title {
+    align-items: baseline;
+    font-size: var(--font-size-sm, 0.8125rem);
+    font-weight: 700;
+    letter-spacing: 0.04em;
+}
+
+/* A pill in a card heading, a bare number everywhere else — a pill on the page
+   ground reads as a badge that means something, and it does not. */
+.count {
+    padding: 0 0.45rem;
+    color: var(--pr-muted);
+    font-size: var(--font-size-xs, 0.75rem);
+    font-weight: var(--font-weight-semibold, 600);
+    font-variant-numeric: tabular-nums;
+    background: var(--pr-surface);
+    border: 1px solid var(--pr-line);
+    border-radius: var(--radius-pill, 999px);
+}
+
+.plain > .head > .title > .count,
+.flush > .head > .title > .count {
+    padding: 0;
+    font-size: var(--font-size-sm, 0.8125rem);
+    font-weight: 400;
+    background: none;
+    border: 0;
+}
+
+.flush > .head > .title > .count {
+    font-size: var(--font-size-xs, 0.75rem);
+}
+
+/* Whatever the band wants to say about itself on the right — a subtotal, a
+   sentence explaining what its dates mean. */
+.meta {
+    display: flex;
+    gap: 0.6rem;
+    align-items: baseline;
+    color: var(--pr-muted);
+    font-size: var(--font-size-xs, 0.75rem);
+}
+
+.plain > .head > .meta {
+    margin-left: auto;
+}
+
+.note {
+    color: var(--pr-muted);
+}

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

@@ -0,0 +1,108 @@
+@use 'surface' as *;
+
+/**
+ * FactsBand — the persistent strip of key facts under a record's title.
+ *
+ * The same hairline grid StatStrip draws in its `joined` variant, at a tighter
+ * density and carrying two kinds of cell rather than one: a FIGURE (a count,
+ * read at a glance) and a VALUE (a name, an address, a phone number — read as
+ * text, and clipped rather than wrapped, because the band's whole job is to keep
+ * a fixed height while the body under it changes).
+ *
+ * It is a separate module from StatStrip on purpose. A stat strip describes a
+ * SET and sits above a list; a facts band describes ONE RECORD and sits under
+ * its title, where it has to survive the tabs beneath it being switched. Merging
+ * them would mean one component with a density prop that changed what its slots
+ * meant, which is the kind of parameter that quietly grows a third value.
+ */
+
+.band {
+    @include surface-tokens;
+
+    display: grid;
+    grid-template-columns: var(
+        --vs-facts-columns,
+        repeat(auto-fit, minmax(var(--vs-facts-min, 11rem), 1fr))
+    );
+    gap: 1px;
+    overflow: hidden;
+    font-size: var(--font-size-sm, 0.8125rem);
+    background: var(--pr-line);
+    border: 1px solid var(--pr-line);
+    border-radius: var(--pr-radius);
+    box-shadow: var(--pr-shadow);
+}
+
+.cell {
+    display: flex;
+    flex-direction: column;
+    gap: 0.15rem;
+    min-width: 0;
+    padding: 0.7rem var(--spacing-md, 1rem);
+    background: var(--pr-surface);
+}
+
+.label {
+    color: var(--pr-muted);
+    font-size: var(--font-size-xs, 0.75rem);
+    font-weight: 600;
+    letter-spacing: 0.02em;
+    text-transform: uppercase;
+}
+
+/* Text, clipped. A band that wraps is a band whose height moves, and the tab
+   strip under it moves with it every time a record loads. */
+.value {
+    overflow: hidden;
+    color: var(--pr-heading);
+    font-weight: var(--font-weight-semibold, 600);
+    text-decoration: none;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+/* `href` turns the value into a `tel:` / `mailto:`, so it has to be obviously
+   tappable without looking like a stray link in a header. */
+a.value:hover {
+    text-decoration: underline;
+}
+
+/* The counts read as figures rather than sentences, so a glance across the band
+   lands on the numbers. */
+.figure {
+    font-size: 1.2rem;
+    font-weight: 700;
+    font-variant-numeric: tabular-nums;
+    line-height: 1.2;
+}
+
+.note {
+    overflow: hidden;
+    color: var(--pr-muted);
+    font-size: var(--font-size-xs, 0.75rem);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.toneAccent {
+    color: var(--pr-accent);
+}
+
+.toneWarn {
+    color: var(--pr-warn);
+}
+
+.toneDanger {
+    color: var(--pr-danger);
+}
+
+/* The band is one row of a card, so a failure to load must not leave a hole in
+   the page where the record's facts were. Full width, same ground, one
+   sentence. */
+.state {
+    grid-column: 1 / -1;
+    padding: 0.7rem var(--spacing-md, 1rem);
+    color: var(--pr-muted);
+    font-size: var(--font-size-xs, 0.75rem);
+    background: var(--pr-surface);
+}

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

@@ -0,0 +1,98 @@
+@use 'surface' as *;
+
+/**
+ * PageHeader — the identity row at the top of a screen.
+ *
+ * Whatever names the page on the left, whatever acts on it hard right, and
+ * nothing behind either: the shape GenericDetail's `.crmtitle` draws, restated
+ * as a component so the six screens that had each written it out by hand stop
+ * drifting apart by a tenth of a rem at a time.
+ *
+ * The left half is deliberately a slot. Some of these pages lead with a
+ * breadcrumb, some with a back link over a title, some with a title and a line
+ * of explanation — and the component's job is the ROW, not a decision about
+ * which of those a page should use.
+ */
+
+.header {
+    @include surface-tokens;
+
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--spacing-md, 1rem);
+    justify-content: space-between;
+
+    /* Breadcrumb wraps its trail in a <nav>; without this the flex item takes
+       its content's minimum width and pushes the actions off the row. */
+    nav {
+        min-width: 0;
+    }
+}
+
+.alignCenter {
+    align-items: center;
+}
+
+.alignStart {
+    align-items: flex-start;
+}
+
+.alignEnd {
+    align-items: flex-end;
+}
+
+/* The quarter-rem of air the breadcrumb-led screens sit in, so the trail is not
+   flush against the page gutter. Opt-in: the title-led screens do not want it. */
+.gutter {
+    padding: 0 0.25rem 0.25rem;
+}
+
+/* Opt-in, and it needs a ground of its own — a transparent sticky header lets
+   the rows scroll through the type underneath it. */
+.sticky {
+    position: sticky;
+    top: 0;
+    z-index: 2;
+    background: var(--pr-surface);
+}
+
+.main {
+    min-width: 0;
+}
+
+.title {
+    margin: 0;
+    padding: 0;
+    color: var(--pr-heading);
+    font-size: var(--vs-header-title-size, var(--page-header-title-size, 1.25rem));
+    font-weight: var(--font-weight-bold, 700);
+    line-height: 1.2;
+}
+
+.subtitle {
+    margin: 0.2rem 0 0;
+    /* Wide enough for a sentence, narrow enough that it stays one. */
+    max-width: 62ch;
+    color: var(--pr-muted);
+    font-size: var(--font-size-sm, 0.8125rem);
+}
+
+.actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    align-items: center;
+}
+
+/* -------------------------------------------------------------------------- */
+/* narrow                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/* The tablet break. Actions under the title rather than squeezed beside it —
+   this app is driven on an iPad in portrait as much as at a desk. */
+@media (max-width: 820px) {
+    .header {
+        flex-direction: column;
+        align-items: stretch;
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * ScrollRegion — the list scrolls, the page stays.
+ *
+ * Deliberately almost empty. The height is inline (measured, see
+ * `useContainedHeight`) and the region must not impose a background, a border or
+ * a radius: it is a scroll box around whatever the host already drew, and giving
+ * it a surface of its own would put a second card edge around a card.
+ */
+
+.region {
+    overflow: auto;
+    /* Narrow screens scroll their overflow HERE rather than tipping the whole
+       document sideways. */
+    overflow-x: auto;
+    /* Momentum on iOS Safari. A no-op everywhere it is not needed. */
+    -webkit-overflow-scrolling: touch;
+    /* `overscroll-behavior` is left at its default on purpose: chaining to the
+       page when the list is finished is the native feel, and containing it is
+       what makes a long page seem stuck. */
+}

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

@@ -0,0 +1,183 @@
+@use 'surface' as *;
+
+/**
+ * StatStrip — the row of labelled figures that sits above a list.
+ *
+ * Two shapes, because the screens it was lifted from genuinely draw two and
+ * neither is wrong:
+ *
+ *   `joined`  one card, cells separated by a hairline. The grid's `gap: 1px`
+ *             is the container's own background showing through, which is how
+ *             the rules stay exactly one device pixel at any zoom. Reads as a
+ *             single statement about the set below it.
+ *   `tiles`   separate bordered tiles with real space between them. Reads as
+ *             independent figures, which is what a dashboard wants — and is
+ *             the only one of the two that can carry a per-tile emphasis skin
+ *             without the tint bleeding across a shared border.
+ *
+ * The track width is a custom property rather than a fixed value so a page can
+ * reflow the strip from its own media query (`--vs-stat-min`), or replace the
+ * track list outright (`--vs-stat-columns`) for the cases auto-fit cannot
+ * express — "exactly two columns on a phone" being the one that keeps coming
+ * up.
+ */
+
+.strip {
+    @include surface-tokens;
+
+    display: grid;
+    grid-template-columns: var(
+        --vs-stat-columns,
+        repeat(auto-fit, minmax(var(--vs-stat-min, 10rem), 1fr))
+    );
+}
+
+/* One card, hairline-separated. */
+.joined {
+    gap: 1px;
+    overflow: hidden;
+    background: var(--pr-line);
+    border: 1px solid var(--pr-line);
+    border-radius: var(--pr-radius);
+    box-shadow: var(--pr-shadow);
+}
+
+/* Separate tiles. */
+.tiles {
+    gap: var(--spacing-md, 1rem);
+}
+
+/* -------------------------------------------------------------------------- */
+/* one figure                                                                 */
+/* -------------------------------------------------------------------------- */
+
+.stat {
+    @include surface-tokens;
+
+    display: flex;
+    flex-direction: column;
+    gap: 0.15rem;
+    min-width: 0;
+    padding: 0.85rem var(--spacing-md, 1rem);
+    background: var(--pr-surface);
+}
+
+.tiles .stat {
+    border: 1px solid var(--pr-line);
+    border-radius: var(--pr-radius);
+}
+
+/* A stat that navigates. It is a real <button>, so everything a button brings
+   with it — the browser's font, the centred text, the 2px agent border — has
+   to be unwound before it can pass for a cell. */
+.interactive {
+    color: inherit;
+    font: inherit;
+    text-align: left;
+    text-decoration: none;
+    border: 0;
+    cursor: pointer;
+    transition: background var(--speed, 160ms) var(--ease, ease);
+
+    &:hover {
+        background: var(--pr-quiet);
+    }
+
+    &:focus-visible {
+        outline: 2px solid var(--pr-accent);
+        outline-offset: -2px;
+    }
+}
+
+.tiles .interactive {
+    border: 1px solid var(--pr-line);
+}
+
+.label {
+    color: var(--pr-muted);
+    font-size: var(--font-size-xs, 0.75rem);
+    letter-spacing: 0.02em;
+    text-transform: uppercase;
+}
+
+/* The label carries a little more weight inside a hairline grid, where there is
+   no border to tell one cell from the next. */
+.joined .label {
+    font-weight: 600;
+}
+
+.value {
+    font-size: 1.35rem;
+    font-weight: var(--font-weight-bold, 700);
+    /* Tabular figures so a column of money lines up on the decimal point. */
+    font-variant-numeric: tabular-nums;
+    line-height: 1.2;
+}
+
+/* In a tile the figure is the tile's whole content, so it takes the heading
+   colour. In a hairline grid it sits in a run of cells and inherits the page's
+   ink instead, or the run reads as six headings. */
+.tiles .value {
+    color: var(--pr-heading);
+    line-height: 1.15;
+}
+
+/* `/mo`, `%`, `h` — the unit rides with the figure at small print rather than
+   being sized up with it. */
+.unit {
+    margin-left: 0.15rem;
+    color: var(--pr-muted);
+    font-size: 0.8rem;
+    font-weight: 400;
+}
+
+.note {
+    color: var(--pr-muted);
+    font-size: var(--font-size-xs, 0.75rem);
+}
+
+/* -------------------------------------------------------------------------- */
+/* tone and emphasis                                                          */
+/* -------------------------------------------------------------------------- */
+
+/* `tone` colours the FIGURE. Applied by the caller only when the figure is
+   non-zero — a tile that is permanently red is a tile nobody reads. */
+.toneAccent {
+    color: var(--pr-accent);
+}
+
+.toneHeading {
+    color: var(--pr-heading);
+}
+
+.toneWarn {
+    color: var(--pr-warn);
+}
+
+.toneDanger {
+    color: var(--pr-danger);
+}
+
+/* A note that has to carry the weight rather than the figure above it — "3
+   unpriced" hanging off a money total. */
+.noteWarn {
+    color: var(--pr-warn);
+    font-weight: var(--font-weight-semibold, 600);
+}
+
+/* `emphasis` skins the whole TILE, and only in the `tiles` variant: a tint
+   inside a hairline grid would bleed to the cell edges and read as a broken
+   border rather than as a warning. */
+.tiles .emphasisWarn {
+    background: color-mix(in srgb, var(--pr-warn) 7%, var(--pr-surface));
+    border-color: color-mix(in srgb, var(--pr-warn) 42%, var(--pr-line));
+}
+
+.tiles .emphasisDanger {
+    background: color-mix(in srgb, var(--pr-danger) 5%, var(--pr-surface));
+    border-color: color-mix(in srgb, var(--pr-danger) 40%, var(--pr-line));
+
+    .value {
+        color: var(--pr-danger);
+    }
+}