@visns-studio/visns-components 6.20.1 → 6.23.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/DataGrid.module.scss

@@ -697,6 +697,16 @@
     width: 100%;
     font-size: 0.9rem;
     box-sizing: border-box;
+    // The input is type="search" (to sidestep host apps' global text-input
+    // rules), so strip WebKit's search decorations to keep it looking like
+    // the plain field it always was.
+    appearance: none;
+    -webkit-appearance: none;
+
+    &::-webkit-search-decoration,
+    &::-webkit-search-cancel-button {
+        -webkit-appearance: none;
+    }
 
     &:focus {
         outline: none;

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/GenericDetail.module.scss

@@ -1362,8 +1362,12 @@
 /* It stays pinned bottom-right — every detail page in every project is laid
    out around that — but it had no ground of its own, so on a short page the
    buttons floated over the page background with nothing behind them. A pill
-   with the same elevation as the panels gives them somewhere to sit. */
-.polActions {
+   with the same elevation as the panels gives them somewhere to sit.
+
+   ONLY when there is more than one of them: a tray around a single solid
+   button reads as a white oval drawn around it, not as ground. A lone
+   button carries its own elevation instead. */
+.polActions:has(> :nth-child(2)) {
     padding: 0.4rem;
     border: 1px solid var(--gd-line);
     border-radius: var(--radius-pill, 999px);
@@ -1374,6 +1378,12 @@
         0 16px 32px -14px color-mix(in srgb, var(--primary-color, #1b3933) 30%, transparent);
 }
 
+.polActions:not(:has(> :nth-child(2))) > * {
+    box-shadow:
+        0 2px 4px color-mix(in srgb, var(--primary-color, #1b3933) 12%, transparent),
+        0 12px 24px -12px color-mix(in srgb, var(--primary-color, #1b3933) 35%, transparent);
+}
+
 /* -- states --------------------------------------------------------------- */
 
 .noDataMessage {

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/Sms.module.scss

@@ -234,6 +234,15 @@ $sms-mono: 'SFMono-Regular', 'Menlo', 'Consolas', monospace;
     }
 }
 
+// A ghost button that is currently ON — the Select toggle while the timeline is
+// in picking mode. Tinted rather than filled: it is a mode, not the pane's
+// primary action.
+.ghostButtonOn {
+    border-color: var(--s-primary);
+    background: var(--s-tint);
+    color: var(--s-primary);
+}
+
 .iconButton {
     @include sms-reset;
     @include sms-focus;
@@ -1521,6 +1530,101 @@ $sms-mono: 'SFMono-Regular', 'Menlo', 'Consolas', monospace;
     font-weight: 600;
 }
 
+// --------------------------------------------------- picking and annotations
+//
+// Both are off unless the host asked for them: `.pickRow` only ever wraps a
+// bubble while the panel is in Select mode, and `.annotations` renders only
+// where the host supplied chips.
+
+// The whole row is the hit target while picking. The checkbox sits on the
+// bubble's own side of the pane so the ticks line up down one margin rather
+// than zig-zagging with the conversation.
+.pickRow {
+    display: flex;
+    gap: 0.5rem;
+    align-items: center;
+    max-width: 100%;
+    padding: 0.15rem 0.25rem;
+    border: 1px solid transparent;
+    border-radius: 14px;
+    cursor: pointer;
+
+    &:hover {
+        background: var(--s-hover);
+    }
+}
+
+.bubbleOut .pickRow {
+    flex-direction: row-reverse;
+}
+
+.pickRowOn {
+    border-color: color-mix(in srgb, var(--s-primary) 45%, transparent);
+    background: var(--s-tint);
+}
+
+// A message that has not reached the server yet — nothing to file it against.
+.pickRowOff {
+    opacity: 0.5;
+    cursor: default;
+
+    &:hover {
+        background: none;
+    }
+}
+
+.pickBox {
+    flex-shrink: 0;
+    width: 15px;
+    height: 15px;
+    margin: 0;
+    accent-color: var(--s-primary);
+    cursor: inherit;
+}
+
+// Host-supplied chips under a bubble, on the bubble's own side.
+.annotations {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem;
+    max-width: min(60ch, 64%);
+    margin-top: 0.25rem;
+    padding: 0 0.25rem;
+}
+
+.bubbleOut .annotations {
+    justify-content: flex-end;
+}
+
+.annotation {
+    @include sms-reset;
+
+    display: inline-flex;
+    gap: 0.25rem;
+    align-items: center;
+    max-width: 100%;
+    padding: 0.1rem 0.5rem;
+    border: 1px solid color-mix(in srgb, var(--s-primary) 30%, transparent);
+    border-radius: 999px;
+    background: var(--s-tint);
+    color: var(--s-primary);
+    font-size: 0.7rem;
+    font-weight: 600;
+    text-align: left;
+    overflow-wrap: anywhere;
+}
+
+.annotationAction {
+    @include sms-focus;
+
+    cursor: pointer;
+
+    &:hover {
+        border-color: var(--s-primary);
+        background: color-mix(in srgb, var(--s-primary) 16%, var(--s-background));
+    }
+}
+
 .retryButton {
     @include sms-reset;
     @include sms-focus;
@@ -1599,6 +1703,33 @@ $sms-mono: 'SFMono-Regular', 'Menlo', 'Consolas', monospace;
     background: var(--s-surface);
 }
 
+// Stands exactly where the composer does while the timeline is being picked
+// over, so the pane keeps its height and its one footer.
+.selectBar {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem 0.75rem;
+    align-items: center;
+    justify-content: space-between;
+    box-sizing: border-box;
+    padding: 0.6rem 0.7rem 0.7rem;
+    border-top: 1px solid var(--s-line);
+    background: var(--s-surface);
+}
+
+.selectCount {
+    color: var(--s-paragraph);
+    font-size: 0.8rem;
+    font-weight: 600;
+}
+
+.selectActions {
+    display: inline-flex;
+    gap: 0.5rem;
+    align-items: center;
+    margin-left: auto;
+}
+
 // One card: the text on top, every control in a bar along its bottom edge.
 // Buttons beside a textarea line up with nothing once the box grows; a bar
 // inside the same border always reads as part of the message being written.