basalt-ui 1.25.0 → 1.27.0

package/src/charts/cursor/scope.tsx

@@ -11,9 +11,12 @@ export type ChartCursorScopeProps = {
 
 /**
  * ISOLATES its subtree onto a private cursor store — the inverse of the removed `ChartHoverSync`, which
- * had to be mounted to enable sharing at all. Charts share a cursor by default now; wrap a group
- * in this only when it must NOT follow the rest of the page (e.g. two independent dashboards
- * rendered side by side over the same calendar).
+ * had to be mounted to enable sharing at all. Charts share a cursor by default now, AND the shared
+ * cursor partitions automatically by x-domain kind (`DomainKind`, derived from each chart's own
+ * data in `useChartCursor`) — a categorical chart never follows a date chart just because both
+ * happen to be on the page, with nothing to configure. `ChartCursorScope` is no longer the tool for
+ * that case. What it is still for: isolating two charts that share the same domain KIND but are
+ * semantically unrelated — two different tenants' date ranges rendered side by side on one page.
  */
 export function ChartCursorScope({ children }: ChartCursorScopeProps) {
   const store = useMemo(() => createCursorStore(), [])

package/src/charts/cursor/store.test.ts

@@ -11,7 +11,7 @@ describe('cursor store', () => {
 
     store.set('2026-08-18', 'chart-a')
     expect(calls).toBe(1)
-    expect(store.get()).toEqual({ key: '2026-08-18', source: 'chart-a' })
+    expect(store.get()).toEqual({ key: '2026-08-18', source: 'chart-a', kind: null })
 
     unsubscribe()
     store.set('2026-08-19', 'chart-a')
@@ -43,4 +43,22 @@ describe('cursor store', () => {
     scoped.set('2026-08-18', 'chart-a')
     expect(globalCursorStore.get().key).toBeNull()
   })
+
+  test('a set carrying a different kind notifies — the partition is state, not a filter on the store', () => {
+    // The store is dumb: it broadcasts whatever kind it's handed and never compares it against
+    // anything. Policing "does this kind match mine" is `useChartCursor`'s job, on read.
+    const store = createCursorStore()
+    let calls = 0
+    store.subscribe(() => {
+      calls++
+    })
+
+    store.set('2026-08-18', 'chart-a', 'time')
+    expect(calls).toBe(1)
+    expect(store.get()).toEqual({ key: '2026-08-18', source: 'chart-a', kind: 'time' })
+
+    store.set('2026-08-18', 'chart-a', 'band')
+    expect(calls).toBe(2)
+    expect(store.get()).toEqual({ key: '2026-08-18', source: 'chart-a', kind: 'band' })
+  })
 })

package/src/charts/cursor/store.ts

@@ -12,22 +12,27 @@
  * on each pointer frame.
  */
 
+import type { DomainKind } from './resolve'
+
 /** Broadcast cursor position: an opaque domain key plus the chart that owns it. */
 export type CursorState = {
   /** The hovered x-domain key (a date/category string), or null when nothing is hovered. */
   key: string | null
   /** `chartId` of the chart the pointer is actually over — the one that owns the tooltip. */
   source: string | null
+  /** The broadcaster's own x-domain kind. `null` only in the empty state — the store itself does
+   * not police this, it just carries it; the partition is enforced by the reading hook. */
+  kind: DomainKind | null
 }
 
 export type CursorStore = {
   get: () => CursorState
-  set: (key: string | null, source: string | null) => void
+  set: (key: string | null, source: string | null, kind?: DomainKind | null) => void
   subscribe: (onChange: () => void) => () => void
 }
 
 /** Stable identity for "nothing hovered" — also the SSR snapshot, so it must never be recreated. */
-export const EMPTY_CURSOR: CursorState = { key: null, source: null }
+export const EMPTY_CURSOR: CursorState = { key: null, source: null, kind: null }
 
 export function createCursorStore(): CursorStore {
   let state: CursorState = EMPTY_CURSOR
@@ -35,9 +40,9 @@ export function createCursorStore(): CursorStore {
 
   return {
     get: () => state,
-    set: (key, source) => {
-      if (state.key === key && state.source === source) return
-      state = key === null && source === null ? EMPTY_CURSOR : { key, source }
+    set: (key, source, kind = null) => {
+      if (state.key === key && state.source === source && state.kind === kind) return
+      state = key === null && source === null ? EMPTY_CURSOR : { key, source, kind }
       for (const listener of listeners) listener()
     },
     subscribe: (onChange) => {

package/src/charts/hooks/useChartCursor.ts

@@ -2,7 +2,7 @@ import { localPoint } from '@visx/event'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { KeyboardEvent, PointerEvent } from 'react'
 import type { CursorResolution } from '../cursor/resolve'
-import { buildDomainIndex, resolveCursorPoint } from '../cursor/resolve'
+import { buildDomainIndex, classifyDomain, resolveCursorPoint } from '../cursor/resolve'
 import { useCursorState, useCursorStore } from '../cursor/scope'
 
 /** Viewport-space pointer anchor the tooltip positions against. */
@@ -70,6 +70,9 @@ export function useChartCursor<T>({
     () => buildDomainIndex(data, getKeyRef.current, resolution),
     [data, resolution],
   )
+  // Mirrors `index`'s memo shape (deps built off `data`, reading the accessor through a ref) —
+  // `resolution` is left out because `kind` never reads it, and `exhaustive-deps` enforces that.
+  const kind = useMemo(() => classifyDomain(data.map((d) => getKeyRef.current(d))), [data])
 
   const frameRef = useRef<number | null>(null)
   const pendingRef = useRef<CursorAnchor | null>(null)
@@ -80,7 +83,7 @@ export function useChartCursor<T>({
       // drops the chart, a tab switches) fires no leave/blur, so the store would keep pointing at
       // a dead chartId — and any sibling whose domain resolves that stale key would paint a ghost
       // crosshair with no way to clear it. Same ownership guard as `clear()`.
-      if (store.get().source === chartId) store.set(null, null)
+      if (store.get().source === chartId) store.set(null, null, null)
     },
     [store, chartId],
   )
@@ -117,9 +120,9 @@ export function useChartCursor<T>({
       }
 
       scheduleAnchor({ x: event.clientX, y: event.clientY })
-      store.set(getKeyRef.current(closest), chartId)
+      store.set(getKeyRef.current(closest), chartId, kind)
     },
-    [data, marginLeft, chartId, store, scheduleAnchor],
+    [data, marginLeft, chartId, store, scheduleAnchor, kind],
   )
 
   const clear = useCallback(() => {
@@ -131,7 +134,7 @@ export function useChartCursor<T>({
     setAnchor(null)
     // Only clear the SHARED cursor if this chart still owns it: moving fast from chart A to B lets
     // A's leave fire after B's move, and an unconditional clear would wipe B's cursor.
-    if (store.get().source === chartId) store.set(null, null)
+    if (store.get().source === chartId) store.set(null, null, null)
   }, [store, chartId])
 
   const onKeyDown = useCallback(
@@ -155,12 +158,17 @@ export function useChartCursor<T>({
       const rect = event.currentTarget.getBoundingClientRect()
       const x = xScaleRef.current(getKeyRef.current(next)) ?? 0
       scheduleAnchor({ x: rect.left + x, y: rect.top })
-      store.set(getKeyRef.current(next), chartId)
+      store.set(getKeyRef.current(next), chartId, kind)
     },
-    [data, store, chartId, clear, scheduleAnchor],
+    [data, store, chartId, clear, scheduleAnchor, kind],
   )
 
-  const point = cursor.key === null ? null : resolveCursorPoint(index, cursor.key)
+  // A broadcast from a domain of a DIFFERENT kind is filtered out here, before resolution is even
+  // attempted — a category chart never resolves a date chart's key just because both happen to
+  // parse. `isSource` is unaffected: it compares `chartId`, not `kind`, and a chart's own broadcast
+  // always carries its own kind by construction.
+  const point =
+    cursor.key === null || cursor.kind !== kind ? null : resolveCursorPoint(index, cursor.key)
 
   return {
     point,

package/src/charts/index.ts

@@ -76,7 +76,7 @@ export {
 } from './primitives/ChartPending'
 export { Crosshair, SeriesDot } from './primitives/Crosshair'
 export { HatchPattern, hatchFill, hatchSizeFor } from './primitives/HatchPattern'
-export { ChartCard } from './primitives/ChartCard'
+export { ChartCard, type ChartCardProps } from './primitives/ChartCard'
 export { ChartLegend, type LegendEntry } from './primitives/ChartLegend'
 export {
   ChartTooltipFloat,
@@ -98,7 +98,7 @@ export {
   type BandTooltipConfig,
   type BandTooltipRowContext,
 } from './hooks/useBandPlot'
-export type { CursorResolution } from './cursor/resolve'
+export type { CursorResolution, DomainKind } from './cursor/resolve'
 export { useChartSize, type UseChartSizeResult, type ChartSize } from './hooks/useChartSize'
 
 // ── Utils ────────────────────────────────────────────────────────────────

package/src/charts/primitives/CartesianChart.test.tsx

@@ -448,6 +448,130 @@ describe('tooltip.onFollow — a follower whose domain never resolves the broadc
   })
 })
 
+describe('cursor partitions by x-domain kind — a band chart never follows a time chart', () => {
+  const categoryRows: Row[] = [
+    { date: 'Visited', a: 100, b: 100 },
+    { date: 'Added to cart', a: 40, b: 40 },
+    { date: 'Purchased', a: 10, b: 10 },
+  ]
+
+  const numericRows: Row[] = [
+    { date: '0', a: 5, b: 5 },
+    { date: '1', a: 6, b: 6 },
+    { date: '2', a: 7, b: 7 },
+  ]
+
+  test('a category-keyed chart renders no crosshair while a date-keyed sibling owns the cursor', async () => {
+    render(
+      <ChartCursorScope>
+        <CartesianChart<Row>
+          data={rows}
+          chartId="kind-time-source"
+          getX={(d) => d.date}
+          series={[seriesFor('a')]}
+          ariaLabel="Source"
+          legend={false}
+        >
+          {() => null}
+        </CartesianChart>
+        <CartesianChart<Row>
+          data={categoryRows}
+          chartId="kind-band-follower"
+          getX={(d) => d.date}
+          series={[seriesFor('b')]}
+          ariaLabel="Follower"
+          legend={false}
+          tooltip={{ follow: false, onFollow: true }}
+        >
+          {() => null}
+        </CartesianChart>
+      </ChartCursorScope>,
+    )
+
+    fireEvent.keyDown(screen.getByRole('slider', { name: 'Source' }), { key: 'ArrowRight' })
+
+    // The SOURCE (time) still renders its own tooltip — the follower (band) never resolves the
+    // broadcast at all, because its kind differs, so it stays silent rather than mounting an empty
+    // tooltip shell.
+    expect(await screen.findByText('a')).toBeTruthy()
+    expect(screen.queryByText('b')).toBeNull()
+    expect(screen.queryAllByRole('tooltip')).toHaveLength(1)
+  })
+
+  test('a second date-keyed chart DOES render the crosshair at the same key — time charts on a page still share', async () => {
+    render(
+      <ChartCursorScope>
+        <CartesianChart<Row>
+          data={rows}
+          chartId="kind-time-source-2"
+          getX={(d) => d.date}
+          series={[seriesFor('a')]}
+          ariaLabel="Source"
+          legend={false}
+        >
+          {() => null}
+        </CartesianChart>
+        <CartesianChart<Row>
+          data={rows}
+          chartId="kind-time-follower"
+          getX={(d) => d.date}
+          series={[seriesFor('b')]}
+          ariaLabel="Follower"
+          legend={false}
+          tooltip={{ follow: false, onFollow: true }}
+        >
+          {() => null}
+        </CartesianChart>
+      </ChartCursorScope>,
+    )
+
+    fireEvent.keyDown(screen.getByRole('slider', { name: 'Source' }), { key: 'ArrowRight' })
+
+    // Both charts are `'time'`-kinded, so the partition never fires and the pair keeps sharing.
+    expect(await screen.findByText('a')).toBeTruthy()
+    expect(await screen.findByText('b')).toBeTruthy()
+    expect(screen.queryAllByRole('tooltip')).toHaveLength(2)
+  })
+
+  // This is the case the OLD `parseKey`-only heuristic got wrong: a numeric domain and a date
+  // domain both parse to a number, so `resolveCursorPoint` used to attempt (and by chance often
+  // succeed at) resolving one against the other. Without `classifyDomain` gating the read, this
+  // test fails — the follower would resolve the source's broadcast key and render 'b'.
+  test('a numeric-keyed chart does not follow a date-keyed sibling either', async () => {
+    render(
+      <ChartCursorScope>
+        <CartesianChart<Row>
+          data={rows}
+          chartId="kind-time-source-3"
+          getX={(d) => d.date}
+          series={[seriesFor('a')]}
+          ariaLabel="Source"
+          legend={false}
+        >
+          {() => null}
+        </CartesianChart>
+        <CartesianChart<Row>
+          data={numericRows}
+          chartId="kind-linear-follower"
+          getX={(d) => d.date}
+          series={[seriesFor('b')]}
+          ariaLabel="Follower"
+          legend={false}
+          tooltip={{ follow: false, onFollow: true }}
+        >
+          {() => null}
+        </CartesianChart>
+      </ChartCursorScope>,
+    )
+
+    fireEvent.keyDown(screen.getByRole('slider', { name: 'Source' }), { key: 'ArrowRight' })
+
+    expect(await screen.findByText('a')).toBeTruthy()
+    expect(screen.queryByText('b')).toBeNull()
+    expect(screen.queryAllByRole('tooltip')).toHaveLength(1)
+  })
+})
+
 /**
  * `xTickValues` — the seam a tick COUNT cannot express.
  *

package/src/charts/primitives/ChartCard.test.tsx

@@ -0,0 +1,66 @@
+/**
+ * `ChartCard`'s header — the `''`-as-hidden-header sentinel is gone (docs/CONTROLS-SPEC.md §2.2):
+ * the header now renders only when at least one of title/info/value/actions/icon/count is set.
+ * Mantine-free (`src/charts/**`), so no `MantineProvider` wrapper is needed — mirrors
+ * `ChartFrame.test.tsx`'s rationale.
+ */
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { ChartCard } from './ChartCard'
+
+describe('the header renders only when it has something to show', () => {
+  test('nothing set — no heading at all', () => {
+    render(
+      <ChartCard>
+        <svg />
+      </ChartCard>,
+    )
+    expect(screen.queryByRole('heading')).toBeNull()
+  })
+
+  test('title alone renders the h3', () => {
+    render(
+      <ChartCard title="Revenue over time">
+        <svg />
+      </ChartCard>,
+    )
+    expect(screen.getByRole('heading', { level: 3, name: 'Revenue over time' })).toBeDefined()
+  })
+
+  test('count alone (no title) still renders the header, with an empty title', () => {
+    render(
+      <ChartCard count={4}>
+        <svg />
+      </ChartCard>,
+    )
+    expect(screen.getByText('4')).toBeDefined()
+  })
+
+  test('value alone renders the header', () => {
+    render(
+      <ChartCard value="$12,483">
+        <svg />
+      </ChartCard>,
+    )
+    expect(screen.getByText('$12,483')).toBeDefined()
+  })
+
+  test('actions alone renders the header, carrying data-basalt-tier="widget"', () => {
+    const { container } = render(
+      <ChartCard actions={<button type="button">Export</button>}>
+        <svg />
+      </ChartCard>,
+    )
+    expect(screen.getByRole('button', { name: 'Export' })).toBeDefined()
+    expect(container.querySelector('[data-basalt-tier="widget"]')).not.toBeNull()
+  })
+
+  test('subtitle alone does NOT render the header', () => {
+    render(
+      <ChartCard subtitle="Net revenue per day">
+        <svg />
+      </ChartCard>,
+    )
+    expect(screen.queryByText('Net revenue per day')).toBeNull()
+  })
+})

package/src/charts/primitives/ChartCard.tsx

@@ -1,92 +1,20 @@
+/**
+ * Standard wrapper for every visx chart (docs/CONTROLS-SPEC.md §2.2) — card with a `WidgetHeader
+ * tier="widget"` title row (icon/info/value/delta/count/actions) plus an optional subtitle, over a
+ * clipped chart body. Do not wrap visx charts in bare divs.
+ *
+ * `WidgetHeader` lives in `src/widget-header/` and is itself Mantine-free, so composing it here
+ * keeps `./charts` resolving with no `@mantine/*` installed (`check-dist-layering.mjs`,
+ * `basalt/token-layer-boundary`). The `actions` slot cannot mount `CtlSlot` (Mantine-coupled) for
+ * the same reason — it carries only `data-basalt-tier="widget"`; a basalt control placed there
+ * sizes itself (`size="ctl"` internally), and a raw Mantine element is not auto-tiered.
+ *
+ * The header renders only when at least one of title/info/value/actions/icon/count is set — ending
+ * the `''`-as-hidden-header sentinel a consumer used to reach for otherwise.
+ */
 import type { CSSProperties, ReactNode } from 'react'
-import { useEffect, useId, useRef, useState } from 'react'
 import { VX } from '../../tokens'
-
-const infoWrapStyle: CSSProperties = {
-  position: 'relative',
-  display: 'inline-flex',
-  alignItems: 'center',
-  marginLeft: 5,
-}
-const infoTriggerStyle: CSSProperties = {
-  appearance: 'none',
-  background: 'none',
-  border: 'none',
-  padding: 0,
-  margin: 0,
-  cursor: 'help',
-  display: 'inline-flex',
-  alignItems: 'center',
-}
-// The tooltip bubble reads like every floating surface — panel bg + shadow-card + card radius
-// (docs/DESIGN-SPEC.md section 5). It opens DOWNWARD (top: 100%) by convention, into/over the
-// chart body. The header is intentionally outside the body's clip box (see `cardStyle` /
-// `bodyClipStyle` below), so the bubble can overhang the card edge without ever being clipped.
-// Mantine-free by design (the charts boundary), so this is a plain hover/focus-state bubble, not
-// a Mantine Tooltip.
-const bubbleStyle: CSSProperties = {
-  position: 'absolute',
-  top: 'calc(100% + 7px)',
-  left: 0,
-  zIndex: 10,
-  maxWidth: 260,
-  width: 'max-content',
-  padding: '7px 10px',
-  borderRadius: VX.radiusCard,
-  backgroundColor: VX.surface.panel,
-  boxShadow: VX.shadowCard,
-  color: VX.muted,
-  fontSize: VX.text.sm,
-  fontWeight: 400,
-  lineHeight: 1.4,
-  whiteSpace: 'normal',
-  pointerEvents: 'none',
-}
-
-function InfoIcon({ title }: { title: string }) {
-  const [open, setOpen] = useState(false)
-  const tipId = useId()
-  const triggerRef = useRef<HTMLButtonElement>(null)
-
-  useEffect(() => {
-    if (!open) return
-    const handlePointerDown = (event: PointerEvent) => {
-      if (triggerRef.current?.contains(event.target as Node)) return
-      setOpen(false)
-    }
-    document.addEventListener('pointerdown', handlePointerDown)
-    return () => document.removeEventListener('pointerdown', handlePointerDown)
-  }, [open])
-
-  return (
-    <span style={infoWrapStyle}>
-      <button
-        ref={triggerRef}
-        type="button"
-        aria-label="More information"
-        aria-describedby={open ? tipId : undefined}
-        onMouseEnter={() => setOpen(true)}
-        onMouseLeave={() => setOpen(false)}
-        onFocus={() => setOpen(true)}
-        onBlur={() => setOpen(false)}
-        onClick={() => setOpen(true)}
-        onKeyDown={(event) => {
-          if (event.key === 'Escape') setOpen(false)
-        }}
-        style={{ ...infoTriggerStyle, color: open ? VX.muted : VX.faint }}
-      >
-        <svg width={11} height={11} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
-          <path d="M12 0C5.373 0 0 5.373 0 12s5.373 12 12 12 12-5.373 12-12S18.627 0 12 0zm0 4a1.5 1.5 0 1 1 0 3 1.5 1.5 0 0 1 0-3zm0 5a1 1 0 0 1 1 1v7a1 1 0 1 1-2 0v-7a1 1 0 0 1 1-1z" />
-        </svg>
-      </button>
-      {open && (
-        <span id={tipId} role="tooltip" style={bubbleStyle}>
-          {title}
-        </span>
-      )}
-    </span>
-  )
-}
+import { WidgetHeader } from '../../widget-header'
 
 // Surfaces resolve per theme via CSS vars, so the styles are static (no useMemo/isDark).
 // Depth = `shadow-card` (a whisper shadow + a 1px ring baked into the same value), never a
@@ -94,14 +22,16 @@ function InfoIcon({ title }: { title: string }) {
 // Card/Paper (same shadow token, same radius token, no intrinsic margin; outer spacing comes
 // from the parent Stack/SimpleGrid gap). Shadow + panel background + card radius all live on
 // this OUTER box, which is never clipped — only the chart body below clips its own bottom
-// corners (`bodyClipStyle`). The header is a direct, unclipped child of this box on purpose: its
-// info-tooltip bubble must be able to overflow the card bounds without being invisibly cut off.
-const cardStyle = {
+// corners (`bodyClipStyle`). The header is a direct, unclipped child of this box on purpose:
+// `WidgetHeader`'s info bubble (`widget-header.module.css`'s `.infoBubble`, which is where the
+// tooltip this file used to own now lives) opens downward past the header's own box, and must be
+// able to overhang the card edge without being invisibly cut off.
+const cardStyle: CSSProperties = {
   borderRadius: VX.radiusCard,
   boxShadow: VX.shadowCard,
   backgroundColor: VX.surface.panel,
 }
-const bodyClipStyle = {
+const bodyClipStyle: CSSProperties = {
   // Clip the chart body to the card's bottom corners — a chart with its own square edges would
   // otherwise poke past the card's border-radius. Only the bottom corners: the body's top edge is
   // interior, sitting under the (unclipped) header. Trade-off: a chart tooltip that overflows the
@@ -109,71 +39,81 @@ const bodyClipStyle = {
   // practice — a consumer rendering an oversized/edge tooltip should portal it out of the card.
   borderBottomLeftRadius: VX.radiusCard,
   borderBottomRightRadius: VX.radiusCard,
-  overflow: 'hidden' as const,
-  padding: '2px var(--mantine-spacing-sm, 0.75rem) var(--mantine-spacing-xs, 0.625rem)',
-}
-const headerStyle = {
-  display: 'flex',
-  justifyContent: 'space-between',
-  alignItems: 'center',
-  // Card inset = spacing xs (vertical) / sm (horizontal). The `--mantine-spacing-*` vars carry
-  // basalt's OWNED scale (theme.spacing.xs 0.625rem / sm 0.75rem); the rem fallbacks keep a
-  // Mantine-free `./charts`-only consumer (no MantineProvider vars) padded identically. No
-  // header/body divider — the title block and the plot read as one continuous surface; a rule here
-  // only doubled the card's shadow-embedded ring and made the header feel heavier.
-  padding: 'var(--mantine-spacing-xs, 0.625rem) var(--mantine-spacing-sm, 0.75rem) 4px',
-}
-const titleColumnStyle = {
-  display: 'inline-flex',
-  flexDirection: 'column' as const,
-  lineHeight: 1.15,
+  overflow: 'hidden',
+  padding: '2px var(--mantine-spacing-sm, 0.8125rem) var(--mantine-spacing-xs, 0.6875rem)',
 }
-const titleStyle = {
-  display: 'inline-flex',
-  alignItems: 'center',
-  fontFamily: 'var(--basalt-font-head)',
-  fontStretch: '88%',
-  fontWeight: 550,
-  fontSize: VX.text.md,
-  color: VX.ink,
+// Card inset = spacing xs (vertical) / sm (horizontal). The `--mantine-spacing-*` vars carry
+// basalt's OWNED scale (theme.spacing.xs 0.6875rem / sm 0.8125rem); the rem fallbacks keep a
+// Mantine-free `./charts`-only consumer (no MantineProvider vars) padded identically. No
+// header/body divider — the title block and the plot read as one continuous surface; a rule here
+// only doubled the card's shadow-embedded ring and made the header feel heavier.
+const headerWrapStyle: CSSProperties = {
+  padding: 'var(--mantine-spacing-xs, 0.6875rem) var(--mantine-spacing-sm, 0.8125rem) 4px',
 }
-const subtitleStyle = {
-  fontSize: VX.text.sm,
-  fontWeight: 400,
-  color: VX.muted,
-  marginTop: 1,
+
+export type ChartCardProps = {
+  /** Optional — the header renders only when this or one of info/value/actions/icon/count is set. */
+  title?: string
+  /** Optional leading icon, forwarded to `WidgetHeader`. */
+  icon?: ReactNode
+  /** Optional muted line rendered below the title row — does NOT by itself trigger the header. */
+  subtitle?: string
+  /** Renders `WidgetHeader`'s info glyph beside the title — a `More information` button whose
+   * bubble opens on hover, focus and click. Never part of the heading's accessible name. */
+  info?: string
+  /** Pre-formatted metric value, on the hero-metric row with `delta`. */
+  value?: string
+  /** Signed delta rendered via `DeltaBadge`, alongside `value`. */
+  delta?: number
+  /** Comparison timeframe forwarded to `DeltaBadge` (e.g. `MoM`). */
+  deltaPeriod?: string
+  /** Mono count tag after the title. */
+  count?: number
+  /** Right-aligned slot — carries `data-basalt-tier="widget"` (no `CtlSlot`; see module doc). */
+  actions?: ReactNode
+  children: ReactNode
 }
 
-/**
- * Standard wrapper for every visx chart — card with info-tooltip title + optional
- * subtitle (the question the chart answers) + optional extra slot (current value
- * badge etc.). Do not wrap visx charts in bare divs.
- */
 export function ChartCard({
   title,
+  icon,
   subtitle,
-  tooltip,
-  extra,
+  info,
+  value,
+  delta,
+  deltaPeriod,
+  count,
+  actions,
   children,
-}: {
-  title: string
-  subtitle?: string
-  tooltip: string
-  extra?: ReactNode
-  children: ReactNode
-}) {
+}: ChartCardProps) {
+  const hasHeader =
+    title !== undefined ||
+    info !== undefined ||
+    value !== undefined ||
+    actions !== undefined ||
+    icon !== undefined ||
+    count !== undefined
+
   return (
     <div style={cardStyle}>
-      <div style={headerStyle}>
-        <span style={titleColumnStyle}>
-          <span style={titleStyle}>
-            {title}
-            <InfoIcon title={tooltip} />
-          </span>
-          {subtitle !== undefined && <span style={subtitleStyle}>{subtitle}</span>}
-        </span>
-        {extra !== undefined && <span>{extra}</span>}
-      </div>
+      {hasHeader && (
+        <div style={headerWrapStyle}>
+          <WidgetHeader
+            tier="widget"
+            title={title ?? ''}
+            {...(icon !== undefined && { icon })}
+            {...(subtitle !== undefined && { subtitle })}
+            {...(info !== undefined && { info })}
+            {...(value !== undefined && { value })}
+            {...(delta !== undefined && { delta })}
+            {...(deltaPeriod !== undefined && { deltaPeriod })}
+            {...(count !== undefined && { count })}
+            {...(actions !== undefined && {
+              actions: <span data-basalt-tier="widget">{actions}</span>,
+            })}
+          />
+        </div>
+      )}
       <div style={bodyClipStyle}>{children}</div>
     </div>
   )