basalt-ui 1.25.0 → 1.27.0

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

@@ -0,0 +1,350 @@
+/*
+ * WidgetHeader — the one heading primitive behind every section/card/table title
+ * (docs/CONTROLS-SPEC.md §2.2). Plain elements only — no `@mantine/*` anywhere in this folder —
+ * so `ChartCard` (inside the `charts/` boundary) can compose it without tripping
+ * `basalt/token-layer-boundary` / `check-dist-layering.mjs`.
+ *
+ * `--vx-space-section-header-height` / `--vx-space-widget-header-height` / `--vx-space-control-gap`
+ * are density-tracking anchors landing alongside this wave (docs/CONTROLS-SPEC.md §5) — referenced
+ * by name with rem fallbacks at their level-0 px value (36/28/6), same idiom as ChartCard's
+ * `--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.
+ */
+
+.root {
+  display: flex;
+  flex-direction: column;
+}
+
+.titleRow {
+  display: flex;
+  align-items: center;
+  gap: var(--vx-space-control-gap, 0.375rem);
+}
+
+/*
+ * Below `sm` the title row WRAPS, which is the safety net for an `actions` slot too wide to sit
+ * beside the title. `flex-wrap` is the right tool precisely because it is conditional: a 30px kebab
+ * fits and stays on the row, while a control whose hypothetical size does not fit takes its own line
+ * instead of squeezing the heading to an ellipsis. No breakpoint arithmetic, no max-width fraction,
+ * and no prop — the row measures the actual content.
+ *
+ * `row-gap` is the 8px rhythm step, so a wrapped slot reads as the line under the title rather than
+ * as a second header. `.actions` keeps its `margin-inline-start: auto`, which on a wrapped line makes
+ * it right-aligned — the same edge it holds when it is on the row.
+ */
+@media (max-width: 47.99375em) {
+  .titleRow {
+    flex-wrap: wrap;
+    row-gap: var(--vx-space-stack-sm);
+  }
+}
+
+.root[data-tier='section'] .titleRow {
+  min-height: var(--vx-space-section-header-height, 2.25rem);
+}
+
+.root[data-tier='widget'] .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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+.heading {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  margin: 0;
+  min-width: 0;
+  font-family: var(--basalt-font-head);
+  font-stretch: 88%;
+  font-weight: 550;
+  font-size: var(--vx-text-md);
+  color: var(--vx-ink);
+}
+
+.root[data-tier='section'] .heading {
+  font-weight: 600;
+}
+
+.root[data-tier='widget'] .heading {
+  font-size: var(--vx-text-sm);
+  color: var(--vx-muted);
+}
+
+.titleText {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/*
+ * The icon slot PINS its glyph's box. A consumer's icon arrives at whatever size its own component
+ * chose (the playground's is 18px), and an 18px mark beside a 13.5px title is a bullet, not a label
+ * icon — so the tier states the size here rather than asking every call site to pass one.
+ */
+/*
+ * The heading's icon box carries COLOUR ONLY — geometry belongs to `theme/icon-slot.module.css`,
+ * which this class is composed onto (`IconSlot className={classes.icon}`). The per-tier SIZE is set
+ * as the slot's own box var below rather than as a `> svg` rule, so it survives whatever the caller's
+ * glyph declares for itself: a `width`/`height` attribute is a presentation attribute and loses to
+ * the slot's CSS, while a `> svg` rule scoped to one component only ever fixed that component.
+ */
+.icon {
+  color: var(--vx-faint);
+}
+
+.root[data-tier='widget'] .icon {
+  --vx-space-icon-size: 0.875rem;
+}
+
+.root[data-tier='section'] .icon {
+  --vx-space-icon-size: 1rem;
+}
+
+/* Mono count tag after the title (C11 — every table/list states its count in its header). Its box is
+ * the `tag` tier (20px), so it never grows the header row it sits in. */
+.count {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  /* Exactly the `tag` tier (20px), not a floor: the mono `VX.text.xs` line box plus
+   * `badgeInset`-y is 23px on its own, so a `min-height` changed nothing and the tag rendered 3px
+   * taller than the tier it is named for — enough to grow a 36px section-header row. `line-height: 1`
+   * is what lets the box be the stated height instead of the text's. */
+  /* `--mantine-scale`-aware, same reconstruction every other ctl/tag-tier box uses (`theme/index.ts`'s
+   * `ctlSizeVars`) — read raw, this box stayed fixed while the Badge/Button beside it in the same
+   * header scaled with `theme.scale`. */
+  height: calc(var(--vx-space-control-height-tag, 1.25rem) * var(--mantine-scale, 1));
+  line-height: 1;
+  border-radius: var(--vx-radius-ctrl);
+  background: var(--vx-surface-subtle);
+  padding: var(--vx-space-badge-inset-y) var(--vx-space-badge-inset-x);
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-xs);
+  font-weight: 500;
+  color: var(--vx-faint);
+}
+
+/*
+ * The hero-metric row — value + delta, directly under the title row, for both tiers. 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.
+ */
+/*
+ * The hero-metric row: the value, then its `DeltaBadge`.
+ *
+ * The gap is the 8px vertical-rhythm step (`--vx-space-stack-sm`), not the 4px it shipped as. 4px is
+ * the rhythm's SMALLEST step — the distance between a label and the thing it labels — and at that
+ * distance the badge read as a superscript hanging off the numeral rather than as a second fact
+ * beside it. It is a token and not a literal so it tracks the density knob with every other spacing
+ * in the header (`deriveSpacing`, `tokens/palette.ts`); `theme/layout-rhythm-css.test.ts`'s sibling
+ * assertion in `widget-header.test.tsx` pins it against exactly the literal it used to be.
+ *
+ * `align-items: center`, not `baseline`. The badge is a BOX with its own padding and a mono 11.5px
+ * label, so aligning its text baseline to a 24px KPI numeral's baseline put the box itself low —
+ * its top edge sat below the numeral's x-height and its bottom edge hung under the numeral's
+ * baseline. A chip beside a numeral is centred on the numeral, the same law the `count` tag in the
+ * title row above already follows.
+ */
+.metrics {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-stack-sm);
+  margin-top: 2px;
+  min-width: 0;
+}
+
+/*
+ * Below `sm` the metric row WRAPS, so the badge drops under the value instead of ellipsizing it.
+ * `nowrap` plus the `.value` clamp below is right on desktop — a `+18.9%` cannot ellipsize and read,
+ * a numeral can — but a KPI's numeral IS the content, and in a 2-up card grid at 390px
+ * `$1294.9k ▲18.9%` rendered as `$129… ▲18.9%`. Truncating the number to protect the delta about the
+ * number is the wrong way round. Conditional like the title row above it: a short value keeps the
+ * badge beside it, and only a value that would otherwise clip gives up the line.
+ */
+@media (max-width: 47.99375em) {
+  .metrics {
+    flex-wrap: wrap;
+    row-gap: 2px;
+  }
+}
+
+/* The value is the row's shrinkable half and the delta badge is not: a pre-formatted numeral can
+ * ellipsize and still read, a `+18.9%` cannot. Without the clamp the badge grew past the header box
+ * and painted over `StatCard`'s 72px sparkline slot beside it. */
+.value {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-kpi);
+  font-weight: 600;
+  letter-spacing: -0.02em;
+  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;
+  flex-shrink: 0;
+  align-items: center;
+  gap: var(--vx-space-control-gap, 0.375rem);
+  margin-inline-start: auto;
+}
+
+/* Directly under the title row, 4px off it — 1px put it inside the title's own line box, so a
+ * section with both read as a two-line heading rather than a heading plus a note. */
+.subtitle {
+  margin-top: 4px;
+  font-size: var(--vx-text-sm);
+  font-weight: 400;
+  color: var(--vx-muted);
+}
+
+/* `data-placement` is read by wave-3 composers wanting a `bleed` layout (docs/CONTROLS-SPEC.md
+ * §2.2's `sparklinePlacement` composer mapping) — this primitive only ever sets `right`. */
+.sparkline {
+  margin-top: 4px;
+}
+
+/* ── info glyph ─────────────────────────────────────────────────────────────────────────────── */
+
+.info {
+  position: relative;
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+}
+
+.infoTrigger {
+  display: inline-flex;
+  align-items: center;
+  appearance: none;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  color: var(--vx-faint);
+  cursor: help;
+}
+
+.infoTrigger:hover,
+.infoTrigger:focus-visible,
+.infoTrigger[data-open='true'] {
+  color: var(--vx-muted);
+}
+
+/*
+ * The tooltip bubble reads like every other floating surface — panel bg + `shadow-card` + card
+ * radius (docs/DESIGN-SPEC.md §5). It opens DOWNWARD by convention, into whatever sits below the
+ * header. `pointer-events: none` so it can never swallow the pointer on its way back to the
+ * trigger's `mouseleave`. Mantine-free by design (this whole folder is), so it is a plain
+ * state-driven bubble rather than a Mantine Tooltip — which is also what makes it composable from
+ * inside the `charts/` boundary.
+ */
+.infoBubble {
+  position: absolute;
+  top: calc(100% + 7px);
+  left: 0;
+  z-index: 10;
+  width: max-content;
+  max-width: 260px;
+  padding: 7px 10px;
+  border-radius: var(--vx-radius-card);
+  background-color: var(--vx-surface-panel);
+  box-shadow: var(--vx-shadow-card);
+  color: var(--vx-muted);
+  font-size: var(--vx-text-sm);
+  font-weight: 400;
+  line-height: 1.4;
+  white-space: normal;
+  pointer-events: none;
+}
+
+/* ── DeltaBadge ─────────────────────────────────────────────────────────────────────────────── */
+
+.deltaBadge {
+  display: inline-flex;
+  flex: none;
+  white-space: nowrap;
+  align-items: center;
+  gap: 3px;
+  border-radius: var(--vx-radius-ctrl);
+  padding: var(--vx-space-badge-inset-y) var(--vx-space-badge-inset-x);
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-xs);
+  font-weight: 600;
+  line-height: 1;
+}
+
+.deltaGlyph {
+  font-size: 0.8em;
+}
+
+.deltaPeriod {
+  margin-inline-start: 4px;
+  font-weight: 500;
+  opacity: 0.6;
+}
+
+/*
+ * Law C15 — the `actions` slot is the tier-2/tier-3 home, and its controls are 30px (`ctl`) or 24px
+ * (`icon`). Below `sm` an `::after` overlay lifts the HIT area to
+ * `--vx-space-touch-control-height` (36px at level 0) without moving the visible box, the same
+ * overlay `shell/page-bar.module.css` draws for the bar. `overflow: visible` is load-bearing:
+ * Mantine's Button/ActionIcon roots are `overflow: hidden`, which clips an overlay that by
+ * definition extends past the box — the clipping only exists for their loading overlay, painted
+ * under `[data-loading]`, which is excluded here.
+ */
+@media (max-width: 47.99375em) {
+  .actions :is(button, a) {
+    position: relative;
+  }
+
+  .actions :is(button, a):not([data-loading]) {
+    overflow: visible;
+  }
+
+  .actions :is(button, a)::after {
+    content: '';
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    translate: -50% -50%;
+    width: 100%;
+    height: 100%;
+    min-width: var(--vx-space-touch-control-height, 2.25rem);
+    min-height: var(--vx-space-touch-control-height, 2.25rem);
+  }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly root: string
+  readonly titleRow: string
+  readonly heading: string
+  readonly titleText: string
+  readonly icon: string
+  readonly count: string
+  readonly metrics: string
+  readonly value: string
+  readonly unit: string
+  readonly actions: string
+  readonly subtitle: string
+  readonly sparkline: string
+  readonly info: string
+  readonly infoTrigger: string
+  readonly infoBubble: string
+  readonly deltaBadge: string
+  readonly deltaGlyph: string
+  readonly deltaPeriod: string
+}
+export default classes

package/src/widget-header/widget-header.test.tsx

@@ -0,0 +1,187 @@
+/**
+ * `WidgetHeader` — the tier/heading contract, the count tag, the actions slot, and the info glyph's
+ * accessibility contract (docs/CONTROLS-SPEC.md §2.2). Mantine-free, so components mount with no
+ * `MantineProvider` at all (unlike `stat-card.test.tsx`'s `renderToStaticMarkup` harness).
+ *
+ * CSS-module class hashes are unavailable under `bun test` (see `app-mobile-nav.test.tsx`'s doc) —
+ * nothing here selects on `classes.*`; every query goes through role/accessible-name/text content.
+ */
+import { fireEvent, render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { WidgetHeader } from './widget-header'
+
+const CSS = readFileSync(join(import.meta.dir, 'widget-header.module.css'), 'utf8')
+
+/** The declaration block of one class in this module — CSS-module hashes are unavailable under
+ *  `bun test`, so the rules themselves are read from the file (same idiom as
+ *  `theme/layout-rhythm-css.test.ts` and `controls/filter-set.test.tsx`). */
+function block(selector: string): string {
+  const start = CSS.indexOf(`${selector} {`)
+  expect(start).toBeGreaterThan(-1)
+  return CSS.slice(start, CSS.indexOf('}', start))
+}
+
+describe('the hero-metric row — value → delta spacing and alignment', () => {
+  test('the value→badge gap is the 8px rhythm step, and a TOKEN so density tracks it', () => {
+    // It shipped as `gap: 4px`. 4px is the rhythm's smallest step — label-to-thing distance — and at
+    // that distance the DeltaBadge read as a superscript hanging off the numeral. A literal would
+    // also have frozen the gap while every other spacing in the header moved with the density knob.
+    const metrics = block('.metrics')
+    expect(metrics).toContain('gap: var(--vx-space-stack-sm)')
+    expect(metrics).not.toContain('gap: 4px')
+    expect(metrics).not.toMatch(/gap:\s*\d/)
+  })
+
+  test('the badge is CENTRED on the value, not baseline-aligned to it', () => {
+    // A DeltaBadge is a padded box with an 11.5px mono label; aligning its TEXT baseline to a 24px
+    // KPI numeral's baseline put the box itself low — top edge under the numeral's x-height, bottom
+    // edge hanging below its baseline. The `count` tag in the title row already centres for the
+    // same reason.
+    const metrics = block('.metrics')
+    expect(metrics).toContain('align-items: center')
+    expect(metrics).not.toContain('align-items: baseline')
+  })
+})
+
+describe('tier picks the heading level', () => {
+  test('section renders an h2', () => {
+    render(<WidgetHeader tier="section" title="Overview" />)
+    expect(screen.getByRole('heading', { level: 2, name: 'Overview' })).toBeDefined()
+  })
+
+  test('widget renders an h3', () => {
+    render(<WidgetHeader tier="widget" title="Active Users" />)
+    expect(screen.getByRole('heading', { level: 3, name: 'Active Users' })).toBeDefined()
+  })
+})
+
+test('count renders a mono tag after the title', () => {
+  render(<WidgetHeader tier="section" title="Recent orders" count={42} />)
+  expect(screen.getByText('42')).toBeDefined()
+})
+
+test('count={0} renders "0" — a real count, distinct from an omitted one', () => {
+  render(<WidgetHeader tier="section" title="Recent orders" count={0} />)
+  expect(screen.getByText('0')).toBeDefined()
+})
+
+test('omitting count renders no tag', () => {
+  render(<WidgetHeader tier="section" title="Recent orders" />)
+  expect(screen.queryByText('0')).toBeNull()
+})
+
+describe('the actions slot renders only when passed', () => {
+  test('absent by default', () => {
+    render(<WidgetHeader tier="widget" title="Active Users" />)
+    expect(screen.queryByRole('button', { name: 'Menu' })).toBeNull()
+  })
+
+  test('present when given', () => {
+    render(
+      <WidgetHeader
+        tier="widget"
+        title="Active Users"
+        actions={<button type="button">Menu</button>}
+      />,
+    )
+    expect(screen.getByRole('button', { name: 'Menu' })).toBeDefined()
+  })
+})
+
+describe('the info glyph', () => {
+  const INFO = 'Measured over the trailing 30 days.'
+
+  test("is named `More information` — the text is NOT the button's accessible name", () => {
+    render(<WidgetHeader tier="widget" title="Uptime" info={INFO} />)
+    expect(screen.getByRole('button', { name: 'More information' })).toBeDefined()
+    expect(screen.queryByRole('button', { name: INFO })).toBeNull()
+  })
+
+  test("leaves the heading's accessible name as the title ALONE", () => {
+    // The glyph used to live inside the heading, so an `info` paragraph was read out with the title
+    // in every headings list. This is the assertion that keeps it outside.
+    render(<WidgetHeader tier="widget" title="Uptime" info={INFO} />)
+    const heading = screen.getByRole('heading', { level: 3 })
+    expect(heading.textContent).toBe('Uptime')
+    expect(heading.querySelector('button')).toBeNull()
+    expect(screen.getByRole('heading', { level: 3, name: 'Uptime' })).toBeDefined()
+  })
+
+  test('the bubble is closed until asked, and describes the trigger while open', () => {
+    render(<WidgetHeader tier="section" title="Uptime" info={INFO} />)
+    const trigger = screen.getByRole('button', { name: 'More information' })
+    expect(trigger.getAttribute('aria-describedby')).toBeNull()
+    expect(screen.queryByRole('tooltip')).toBeNull()
+
+    fireEvent.focus(trigger)
+    const bubble = screen.getByRole('tooltip')
+    expect(bubble.textContent).toBe(INFO)
+    expect(trigger.getAttribute('aria-describedby')).toBe(bubble.id)
+  })
+
+  test('KEYBOARD reaches it — focus opens, Escape and blur close', () => {
+    // A `title` attribute alone rendered on hover only, which is the whole reason this bubble exists.
+    render(<WidgetHeader tier="widget" title="Uptime" info={INFO} />)
+    const trigger = screen.getByRole('button', { name: 'More information' })
+
+    fireEvent.focus(trigger)
+    expect(screen.getByRole('tooltip')).toBeDefined()
+
+    fireEvent.keyDown(trigger, { key: 'Escape' })
+    expect(screen.queryByRole('tooltip')).toBeNull()
+
+    fireEvent.focus(trigger)
+    fireEvent.blur(trigger)
+    expect(screen.queryByRole('tooltip')).toBeNull()
+  })
+
+  test('a pointer-down outside closes it', () => {
+    render(<WidgetHeader tier="widget" title="Uptime" info={INFO} />)
+    fireEvent.click(screen.getByRole('button', { name: 'More information' }))
+    expect(screen.getByRole('tooltip')).toBeDefined()
+
+    fireEvent.pointerDown(document.body)
+    expect(screen.queryByRole('tooltip')).toBeNull()
+  })
+})
+
+test('omitting info renders no glyph', () => {
+  render(<WidgetHeader tier="widget" title="Uptime" />)
+  expect(screen.queryByRole('button')).toBeNull()
+})
+
+test('value + delta render together, delta via DeltaBadge', () => {
+  render(<WidgetHeader tier="widget" title="Active Users" value="12,483" delta={4.2} />)
+  expect(screen.getByText('12,483')).toBeDefined()
+  expect(screen.getByText('4.2%')).toBeDefined()
+})
+
+describe('value + delta render on their own row under the title, for both tiers', () => {
+  for (const tier of ['section', 'widget'] as const) {
+    test(tier, () => {
+      render(<WidgetHeader tier={tier} title="Active Users" value="12,483" delta={4.2} />)
+      const valueNode = screen.getByText('12,483')
+      // Never inline with the title — the heading holds title/icon/info/count/actions only.
+      expect(valueNode.closest('h2, h3')).toBeNull()
+    })
+  }
+})
+
+test('subtitle renders below the title row', () => {
+  render(<WidgetHeader tier="section" title="Profile" subtitle="Your public identity." />)
+  expect(screen.getByText('Your public identity.')).toBeDefined()
+})
+
+test('the sparkline slot carries a data-placement for a future bleed layout', () => {
+  render(
+    <WidgetHeader
+      tier="widget"
+      title="Active Users"
+      sparkline={<span data-testid="spark">trend</span>}
+    />,
+  )
+  const spark = screen.getByTestId('spark')
+  expect(spark.closest('[data-placement]')?.getAttribute('data-placement')).toBe('right')
+})