basalt-ui 1.26.0 → 1.28.0

package/src/tokens/palette.ts

@@ -547,8 +547,6 @@ const SPACE_STEP_BASE = {
   mermaidContainerInset: 16,
 
   // ── shell/app-sidebar.module.css (beyond the shared/reused anchors above) ────────────────────
-  /** Brand row's top inset. */
-  sidebarBrandInsetTop: 2,
   /** Brand row's horizontal inset. */
   sidebarBrandInsetX: 7,
   /** Gap between nav sections. */
@@ -613,6 +611,19 @@ const SPACE_STEP_BASE = {
   /** AppShell navbar width, collapsed icon rail. Separate from `appShellHeaderHeight` above
    *  despite sharing 48 at level 0 (see that entry's note). */
   appShellNavbarRailWidth: 48,
+  /** AppShell ASIDE width, unfolded — the right-hand panel region a route claims by rendering
+   *  `PageAside` (`docs/ASIDE-SPEC.md` §0). ONE entry for every viewport, same reasoning as
+   *  `appShellNavbarWidth`: below `sm` the aside is permanently collapsed and `PageAside` renders
+   *  its content in the page flow instead, so there is no second value to keep in step.
+   *
+   *  300, wider than the navbar rail column it mirrors, because the panel holds CONTENT (label-
+   *  above inspector rows, a facet list, a panel-width chart) rather than one row of nav labels —
+   *  it is the width the CBBI evidence page arrived at by hand (`docs/ASIDE-SPEC.md` §2, G13). */
+  appShellAsideWidth: 300,
+  /** AppShell aside width, FOLDED — the rail holding the single expand button. Narrower than
+   *  `appShellNavbarRailWidth` (48) on purpose: the navbar rail hosts a full icon nav row and its
+   *  hover targets, this one hosts exactly one `ctl`-tier icon button and nothing else. */
+  appShellAsideRailWidth: 36,
 
   // ── shell/app-mobile-nav.module.css ───────────────────────────────────────────────────────────
   /** Tab's icon-to-label gap. */
@@ -629,8 +640,12 @@ const SPACE_STEP_BASE = {
   mobileNavTabInsetY: 2,
   /** Active-pill inset around the slot icon, horizontal. */
   mobileNavTabInsetX: 12,
-  /** Menu/sheet row height. Floored at 44px in `deriveSpacing` (Apple HIG 44pt / WCAG 2.5.5 AAA). */
-  mobileNavRowHeight: 44,
+  /** Menu/sheet row height. Floored at 40px in `deriveSpacing` — a deliberate design choice, not
+   *  a WCAG floor: it's the row height shared with the desktop sidebar rows, above the WCAG 2.5.8
+   *  AA minimum (24px) and below the 2.5.5 AAA figure (44px, the size `mobileNavBarHeight`/
+   *  `sheetRowHeight` still hold to) — the shortest box that still reads as ONE row vocabulary with
+   *  the sidebar instead of a bespoke touch size. */
+  mobileNavRowHeight: 40,
   /** More/group `<Menu width={…}>`. JS-consumed, no var — same rationale as
    *  `sidebarSettingsMenuWidth` directly above. */
   mobileNavMenuWidth: 232,
@@ -864,22 +879,26 @@ const ROW_LINE_HEIGHT_STEP = 1 / 30
  *    value) below the accessible floor (22px at level -3) while also crowding out its fixed-size icon
  *    and `Kbd` chip.
  *  - `step.stickyHeaderClearance` is not scaled off its own base AT ALL — `SPACE_STEP_BASE` has no
- *    such key any more (see that table's doc). It is computed AFTER the rest of `step`, as
- *    `step.appShellHeaderHeight + anchors.stackMd`. An independent literal can only be tuned against
- *    ONE header height and then drifts from it: the original 84 was tuned against a 48px desktop
- *    header and under-cleared the pre-1.26.0 96px mobile one by 12px at level 0, before density
- *    entered the picture at all. Deriving it removes that whole failure mode — and since 1.26.0 the
- *    AppShell header is ONE 48px row at every viewport (law C14), so the `stickyHeaderClearanceMobile`
- *    half of the old responsive pair is deleted rather than re-derived. The `+ anchors.stackMd`
- *    breathing room (not a bare `+ 0`) keeps a scrolled-to heading off the header's bottom edge, and
- *    tracks density like the header height it is added to, so the margin never freezes at one notch.
- *    Level 0: `48 + 12 = 60` (a deliberate BREAK from the pre-derivation 84 — see
- *    `theme/spacing.test.ts` for why `stickyHeaderClearance` alone is exempt from the byte-identity
- *    gate every other spacing token is held to).
- *    **Consumer coupling (accepted, not hidden):** the value assumes `BasaltShell`'s own AppShell
- *    header height — a `./content` consumer NOT rendering inside `BasaltShell` (e.g. `Prose`/
- *    `ArticleLayout` standalone) gets a clearance number tuned for a header it may not have, and must
- *    override `--vx-space-sticky-header-clearance` itself. Documented on the `./content` surface too
+ *    such key any more (see that table's doc). It is computed AFTER the rest of `step`, and it is
+ *    now exactly `anchors.stackMd` — pure BREATHING ROOM, with no chrome height folded into it.
+ *    It used to be `step.appShellHeaderHeight + anchors.stackMd` (60 at level 0), which was correct
+ *    while the DOCUMENT scrolled under a fixed 48px app header. It no longer does: `BasaltShell`
+ *    makes `AppShell.Main` the scrollport (`shell/app-main.module.css`), and the header sits OUTSIDE
+ *    that box — so a clearance that still counted the header parked every scrolled-to heading and
+ *    every sticky rail 48px too far down, inside the content instead of above it.
+ *    What the two consumers need is the chrome INSIDE the scrollport — but `PageBar` row 2 now
+ *    portals into a shell-owned band outside the scrollport (see `shell/page-bar.tsx`), so there is
+ *    no page-bar term left to add: both `content/prose.module.css`'s `scroll-margin-top` and
+ *    `content/article-layout.module.css`'s `.tocRail` now use `--vx-space-sticky-header-clearance`
+ *    alone. Keeping the token free of any chrome assumption is what makes it honest on a page with
+ *    no page bar, which is most of them.
+ *    The value still tracks density (it IS a density anchor), so the margin never freezes at one
+ *    notch. Level 0: 12 (a second deliberate BREAK from the byte-identity gate — see
+ *    `theme/spacing.test.ts` for why `stickyHeaderClearance` alone is exempt from it).
+ *    **Consumer coupling (removed, not hidden):** the value no longer assumes ANY header height, so
+ *    a `./content` consumer outside `BasaltShell` (e.g. `Prose`/`ArticleLayout` standalone) gets a
+ *    number that is correct for it too. A consumer with its OWN fixed chrome above the scrollport
+ *    still overrides `--vx-space-sticky-header-clearance`. Documented on the `./content` surface too
  *    (`docs/CONTENT-SPEC.md` §5), not only here.
  *
  * `rowLineHeight` is the ONE exception to the multiplier entirely: `1.35 + ROW_LINE_HEIGHT_STEP *
@@ -980,17 +999,25 @@ export function deriveSpacing(level: number): SpaceValues {
   // Touch targets: the 1 + 0.1*level multiplier would take 56 -> 39 and 44 -> 31 at level -3,
   // silently breaking the minimum interactive-target size. Same guardrail, same reason, as the
   // sidebar search trigger's 24px floor directly above.
-  mappedStep.mobileNavBarHeight = Math.max(48, mappedStep.mobileNavBarHeight)
-  mappedStep.mobileNavRowHeight = Math.max(44, mappedStep.mobileNavRowHeight)
+  //
+  // The floor is 49, not 48: this value feeds `AppShell.Footer`'s `height` prop directly
+  // (shell/index.tsx), and Mantine draws the region-seam `border-top` ON THAT BOX
+  // (`[data-with-border]`, docs/DESIGN-SPEC.md §5) under global `box-sizing: border-box`. The
+  // border eats 1px of the box the floor sizes, so `.bar` (height: 100% of the footer's content
+  // box) would render at 47px if the floor stopped at 48. +1 buys back exactly the pixel the seam
+  // claims, so the tappable bar itself still measures >= 48.
+  mappedStep.mobileNavBarHeight = Math.max(49, mappedStep.mobileNavBarHeight)
+  mappedStep.mobileNavRowHeight = Math.max(40, mappedStep.mobileNavRowHeight)
   // Same floor family, same reason — `sheetRowHeight`'s own doc names it "same floor family as
   // `mobileNavRowHeight`", but nothing enforced that below level 0 until now.
   mappedStep.sheetRowHeight = Math.max(44, mappedStep.sheetRowHeight)
   const step: SpaceValues['step'] = {
     ...mappedStep,
-    // DERIVED from the header it clears, plus density-tracking breathing room — see this function's
+    // Density-tracking breathing room and NOTHING else — the app header is outside the scrollport
+    // now, so folding its height in here would push every consumer down by it. See this function's
     // doc (third bullet) for the full rationale, and `theme/spacing.test.ts` for why
     // `stickyHeaderClearance` alone is exempt from the level-0 byte-identity gate.
-    stickyHeaderClearance: mappedStep.appShellHeaderHeight + anchors.stackMd,
+    stickyHeaderClearance: anchors.stackMd,
   }
 
   return {
@@ -1231,12 +1258,13 @@ function buildPaletteDataUncached(config: DeriveConfig) {
     },
     // Input field surface (docs/DESIGN-SPEC.md §5 field idiom) — reads slightly inset ON a panel.
     field: DERIVED.surface.field,
-    // Hand-authored: the generator has no `divider` stop — layout separators (header bottom rule,
-    // sidebar child indent) stay a fixed-opacity color-mix, distinct from the card ring.
-    divider: {
-      light: 'color-mix(in srgb, #e5e5e5 65%, transparent)',
-      dark: 'color-mix(in srgb, #ffffff 6%, transparent)',
-    },
+    // The SEAM token (docs/DESIGN-SPEC.md §5 "Region seams") — every `AppShell` region edge and
+    // every between-rows rule reads it. A relative alpha over the DERIVED ink, the same law as
+    // `NEUTRAL.grid` above (ink over light, white over dark), so it survives every derive knob and
+    // neutral seed: the old `#e5e5e5` hex flipped polarity at `lightLevel <= -3` and was a grey
+    // line on a slate page. Not the card ring (`hairline`), not the control/overlay line
+    // (`border`). `divider-contrast.test.ts` pins the floor.
+    divider: { light: inkRgba(inkLight, 0.09), dark: 'rgba(255, 255, 255, 0.08)' },
   } as const
 
   return { ACCENT, FILL, SURFACE, INK, NEUTRAL, SEMANTIC, STATUS }

package/src/utils/is-dev.ts

@@ -0,0 +1,4 @@
+/** Dev-mode gate. Bundlers constant-fold `process.env.NODE_ENV` so the branch disappears in production builds. */
+export function isDev(): boolean {
+  return process.env['NODE_ENV'] !== 'production'
+}

package/src/widget-header/delta-badge.tsx

@@ -1,9 +1,13 @@
 /**
  * DeltaBadge — the KPI trend chip (docs/DESIGN-SPEC.md §5): mono 11.5px weight 600, status-color
- * text on a status-13% tint, control radius, 2px/7px padding, optional ▲/▼ glyph at 9px. Sign
- * alone drives the tone — positive reads as success, negative as danger, zero as a neutral faint
- * tint with no glyph. The label never carries a leading "+"; pass `format` to control the
- * magnitude string (defaults to a one-decimal percentage of the absolute value).
+ * text on a status-13% tint, control radius, 2px/7px padding, optional ▲/▼ glyph at 9px.
+ * `polarity` decides the TONE the sign maps to — `'up-good'` (default) reads a rise as success and
+ * a fall as danger; `'up-bad'` inverts that for a metric where a rise is the worse reading (a
+ * cycle-top index, latency, error rate); `'neutral'` renders every sign in a faint, non-verdict
+ * tint. Zero is always faint with no glyph, under every polarity. The label never carries a
+ * leading "+"; pass `format` to control the magnitude string (defaults to a one-decimal percentage
+ * of the absolute value). The ▲/▼ glyph is DIRECTION, not verdict, and stays polarity-independent —
+ * governed only by `withGlyph` and the sign.
  *
  * Mantine-free (plain `<span>` + this folder's CSS module, docs/CONTROLS-SPEC.md §2.2) so
  * `WidgetHeader` can compose it from inside `charts/` without tripping `basalt/token-layer-
@@ -16,13 +20,21 @@
  * <DeltaBadge value={-3.1} />                           // ▼ 3.1%, danger tint
  * <DeltaBadge value={0} />                              // 0.0%, neutral faint tint, no glyph
  * <DeltaBadge value={182} format={(v) => `${Math.abs(v)}ms`} withGlyph={false} />
+ * <DeltaBadge value={35.9} polarity="up-bad" />         // ▲ 35.9%, danger tint — a rise is bad here
  */
 import { alpha, VX } from '../tokens'
 import classes from './widget-header.module.css'
 
+export type DeltaPolarity = 'up-good' | 'up-bad' | 'neutral'
+
 export type DeltaBadgeProps = {
   /** Signed delta driving tone (positive/negative/zero) and, by default, the label magnitude. */
   value: number
+  /** Which sign reads as the good verdict. `'up-good'` (default) is today's behaviour — positive
+   * success, negative danger. `'up-bad'` inverts it for a metric where a rise is the worse reading.
+   * `'neutral'` renders every sign in the faint tint — a change with no verdict attached. Zero is
+   * always faint regardless. */
+  polarity?: DeltaPolarity
   /** Formats the value into the label text. Defaults to `${Math.abs(value).toFixed(1)}%`. */
   format?: (value: number) => string
   /** Render the ▲/▼ direction glyph. Defaults to `true`; a zero value never shows a glyph. */
@@ -34,13 +46,21 @@ export type DeltaBadgeProps = {
 
 const defaultFormat = (value: number): string => `${Math.abs(value).toFixed(1)}%`
 
+function resolveTone(value: number, polarity: DeltaPolarity): string {
+  if (value === 0 || polarity === 'neutral') return VX.faint
+  const rose = value > 0
+  const good = polarity === 'up-good' ? rose : !rose
+  return good ? VX.status.good : VX.status.bad
+}
+
 export function DeltaBadge({
   value,
+  polarity = 'up-good',
   format = defaultFormat,
   withGlyph = true,
   period,
 }: DeltaBadgeProps) {
-  const tone = value > 0 ? VX.status.good : value < 0 ? VX.status.bad : VX.faint
+  const tone = resolveTone(value, polarity)
   const glyph = value > 0 ? '▲' : value < 0 ? '▼' : undefined
   const showGlyph = withGlyph && glyph !== undefined
 

package/src/widget-header/index.ts

@@ -1,2 +1,10 @@
-export { WidgetHeader, type WidgetHeaderProps } from './widget-header'
-export { DeltaBadge, type DeltaBadgeProps } from './delta-badge'
+export {
+  WidgetHeader,
+  type WidgetHeaderDeltaProps,
+  type WidgetHeaderMetricProps,
+  type WidgetHeaderProps,
+  type WidgetHeaderSlot,
+  type WidgetHeaderTier,
+  type WidgetHeaderTitleProps,
+} from './widget-header'
+export { DeltaBadge, type DeltaBadgeProps, type DeltaPolarity } from './delta-badge'

package/src/widget-header/widget-header.module.css

@@ -10,7 +10,7 @@
  * `--mantine-spacing-*` fallbacks.
  *
  * Layout: the title row holds title/icon/info/count/actions only. `value` + `delta` render on
- * their own hero-metric row directly beneath it — for BOTH tiers, never inline with the title.
+ * their own hero-metric row directly beneath it — for every tier, never inline with the title.
  */
 
 .root {
@@ -40,24 +40,75 @@
     flex-wrap: wrap;
     row-gap: var(--vx-space-stack-sm);
   }
+
+  /*
+   * WRAP ONLY WHEN IT DOES NOT FIT (M4 follow-up) — `flex: 1 1 100%` forced EVERY actions slot onto
+   * its own row, even a single 24px icon that fit beside the title fine (a KPI card's lone `···`
+   * menu dropped under the title and pushed the value down with it). `flex: 0 1 auto` restores
+   * ordinary flex sizing: no grow, so a short slot stays put beside the title on the shared row;
+   * `min-width: 0` plus `flex-shrink: 1` (part of the same shorthand, overriding the base rule's
+   * `flex-shrink: 0`) let it shrink and, once `.titleRow`'s own `flex-wrap: wrap` decides it truly
+   * does not fit, drop to its own line. `max-width: 100%` is the cap once it IS alone on that line —
+   * without it a `.actions` still carrying unshrinkable content (the `visibleFrom="sm"` control plus
+   * a nowrap switch `Group`, see below) can overflow the card rather than shrink into it. The base
+   * rule's `margin-inline-start: auto` still applies in both states — right-aligned beside the title
+   * when it fits, right-aligned as the lone item on its own wrapped line when it does not.
+   *
+   * `.actions` keeps its OWN `flex-wrap: wrap` from the prior fix: `Section` can hand it a `tabs`
+   * control (`CtlSlot`-wrapped) AND an `actions` control (another `CtlSlot`) in the same slot, and
+   * without this a nowrap `Group` of switches beside a view-switch control gets squeezed into one
+   * shared line and overflows below its own min-content width — the exact regression this rule
+   * once fixed. It is orthogonal to the row-level "wrap only when it does not fit" law above: with
+   * one child, wrapping has nothing to do, so a lone `···` menu still stays on the title line.
+   *
+   * The real flex items get `flex: 1 1 auto; min-width: 0` so they can shrink or (via the `> * > *`
+   * twin) stack within whatever width `.actions` itself resolves to — a full-width phone `Select`
+   * still reads as its own full-width line because the CONTROL sets that itself (`ViewTabs`'
+   * `fullWidth`/`.phoneSelect`), not because `.actions` forces it.
+   *
+   * The `> * > *` twin exists because `CtlSlot` (`theme/ctl-theme.tsx`) wraps a home's actions in a
+   * `display: contents` box — invisible to the flex box tree, so its OWN children (not it) are the
+   * real flex items. `display: contents` elements still match `.actions > *` by DOM structure but
+   * carry no box to apply `flex`/`min-width` to, hence styling one level deeper as well; a call site
+   * that skips `CtlSlot` and hands `actions` a real element directly gets the same rule from the
+   * first selector.
+   */
+  .actions {
+    flex: 0 1 auto;
+    flex-wrap: wrap;
+    min-width: 0;
+    max-width: 100%;
+  }
+
+  .actions > *,
+  .actions > * > * {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
 }
 
 .root[data-tier='section'] .titleRow {
   min-height: var(--vx-space-section-header-height, 2.25rem);
 }
 
-.root[data-tier='widget'] .titleRow {
+/* `group` shares the `widget` tier's row height — an inspector/aside group label carries no more
+ * vertical weight than a card's own title. */
+.root[data-tier='widget'] .titleRow,
+.root[data-tier='group'] .titleRow {
   min-height: var(--vx-space-widget-header-height, 1.75rem);
 }
 
 /*
- * Section → h2, widget → h3, and the two tiers now read DIFFERENTLY on purpose — they did not, and
- * that is what flattened the page.
+ * Section → h2, widget → h3, group → h3, and the three tiers now read DIFFERENTLY on purpose — they
+ * did not, and that is what flattened the page.
  *
  * A `section` heading names a region of the page: 15px, weight 600, INK. A `widget` heading labels a
  * number that is itself the thing being read (a KPI card's hero value, a chart card's total), so it
  * is the quieter of the pair — one step down and MUTED, which is what lets the 24px mono value under
- * it carry the card. Both keep the shared head-font 88% stretch.
+ * it carry the card. A `group` heading is quieter still: the sidebar's own micro-label recipe (mono,
+ * uppercase, faint), because an inspector/aside group ("Presets", "Composition") must never outrank
+ * a canvas card's title. All three keep the shared head-font 88% stretch as their base, though
+ * `group` overrides every visual property of it (see below).
  *
  * Rendered identically (15px ink both) the hero value competed with its own label, four cards in a
  * row read as four headings, and the section that grouped them read as one more of the same.
@@ -84,6 +135,18 @@
   color: var(--vx-muted);
 }
 
+/* The `group` tier's heading — the sidebar `.sectionLabel` recipe (`shell/app-sidebar.module.css`),
+ * the quietest heading rank on the page. An inspector/aside group label, not a title. */
+.root[data-tier='group'] .heading {
+  font-family: var(--basalt-font-mono);
+  font-stretch: normal;
+  font-size: var(--vx-text-micro);
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--vx-faint);
+}
+
 .titleText {
   overflow: hidden;
   text-overflow: ellipsis;
@@ -106,7 +169,8 @@
   color: var(--vx-faint);
 }
 
-.root[data-tier='widget'] .icon {
+.root[data-tier='widget'] .icon,
+.root[data-tier='group'] .icon {
   --vx-space-icon-size: 0.875rem;
 }
 
@@ -139,7 +203,7 @@
 }
 
 /*
- * The hero-metric row — value + delta, directly under the title row, for both tiers. The delta rides
+ * The hero-metric row — value + delta, directly under the title row, for every tier. The delta rides
  * 4px off the value, not 8: it is a suffix ON the number (`$168,920 +47%`), and at 8px it read as a
  * second, unrelated chip in the row. `baseline` alignment is what keeps the mono numeral and the
  * badge's own smaller mono text sitting on one line.
@@ -199,6 +263,21 @@
   color: var(--vx-ink);
 }
 
+/*
+ * The unit beside the hero value. Mono like the number it qualifies (so `412 TSS` sits on one
+ * baseline grid), `--vx-text-sm` and `--vx-muted` so it never competes with the numeral — the whole
+ * point is that a unit is the SMALL half of the pair. `flex-shrink: 0`: the value is the row's
+ * shrinkable half (see `.value`), and a unit that ellipsized to `TS…` would state nothing.
+ */
+.unit {
+  flex-shrink: 0;
+  align-self: baseline;
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-sm);
+  font-weight: 500;
+  color: var(--vx-muted);
+}
+
 /* The C1/C5 home for header actions — always pinned right, regardless of what else is present. */
 .actions {
   display: inline-flex;
@@ -206,6 +285,7 @@
   align-items: center;
   gap: var(--vx-space-control-gap, 0.375rem);
   margin-inline-start: auto;
+  min-width: 0;
 }
 
 /* Directly under the title row, 4px off it — 1px put it inside the title's own line box, so a

package/src/widget-header/widget-header.module.css.d.ts

@@ -11,6 +11,7 @@ declare const classes: {
   readonly count: string
   readonly metrics: string
   readonly value: string
+  readonly unit: string
   readonly actions: string
   readonly subtitle: string
   readonly sparkline: string