basalt-ui 1.27.0 → 1.29.0

package/src/dashboard/widget-grid.tsx

@@ -0,0 +1,127 @@
+/**
+ * WidgetGrid — the dashboard's column law, owned once (audit B #6/#7).
+ *
+ * Every consumer hand-wrote it: `SimpleGrid cols={{ base: 1, md: 3 }}` on one page,
+ * `cols={{ base: 1, sm: 2, lg: 3 }}` on the next, `Grid.Col span={{ base: 12, md: 8 }}` on a third
+ * — three different breakpoint sets for the same shape, in one app. That is not a styling
+ * preference, it is a layout law nobody owned, and the cost is that a card is 2-up on one route and
+ * 3-up on another at the same viewport.
+ *
+ * **`cols` is the DESKTOP count, and it is the only number a consumer states.** The law is
+ * `base 1 → sm min(cols, 2) → lg cols`: a phone gets one column because a dashboard card holds a
+ * chart; a tablet gets at most two because a third makes every chart narrower than
+ * `VX.phoneChartWidth`; the full count lands at `lg`. Mantine's `cols={{ … }}` object is
+ * deliberately NOT forwarded — a responsive object on the public prop is exactly the seam that let
+ * five call sites disagree.
+ *
+ * **This is the sanctioned place `lg` enters the package.** `sm` is still the only breakpoint a
+ * consumer writes (`docs/CONTROLS-SPEC.md` §2); `WidgetGrid` and `StatGroup` own `lg` internally so
+ * nobody else has to.
+ *
+ * `WidgetGrid.Item` is for the one card that is wider than the rest — a hero chart beside two
+ * stacked panels. `span` is likewise the DESKTOP span and is CLAMPED to the live column count at
+ * each breakpoint, so a `span={3}` in a 2-up `sm` row cannot spill into an implicit third track.
+ * A child rendered WITHOUT an `Item` simply occupies one column; the wrapper is not required.
+ *
+ * @example
+ * import { WidgetGrid } from 'basalt-ui'
+ *
+ * <WidgetGrid cols={3}>
+ *   <ChartCard title="Revenue">…</ChartCard>
+ *   <ChartCard title="Sessions">…</ChartCard>
+ *   <ChartCard title="Errors">…</ChartCard>
+ * </WidgetGrid>
+ *
+ * @example
+ * // The 8/4 split every dashboard has, without a 12-column vocabulary.
+ * <WidgetGrid cols={3}>
+ *   <WidgetGrid.Item span={2}>
+ *     <ChartCard title="Total sales over time">…</ChartCard>
+ *   </WidgetGrid.Item>
+ *   <Section title="Top channels">…</Section>
+ * </WidgetGrid>
+ */
+import { createContext, useContext, useMemo } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import classes from './widget-grid.module.css'
+
+/** The desktop column count. Four is the ceiling: a fifth widget column is a KPI row — `StatGroup`. */
+export type WidgetGridCols = 1 | 2 | 3 | 4
+
+/** The resolved counts at the two breakpoints the law names. Base is always 1 and needs no member. */
+type ResolvedCols = { readonly sm: number; readonly lg: number }
+
+/**
+ * The live column count, published so `WidgetGrid.Item` can CLAMP its span against it. A context
+ * rather than a CSS `min()` because `grid-column: span <n>` takes an integer, not a calculation —
+ * and an unclamped span is the failure that looks like a bug: a `span={3}` inside a 2-up row opens
+ * a third, empty implicit track and every sibling below it goes out of alignment.
+ *
+ * The default is the component's own `cols` default, so an `Item` rendered outside a grid (a
+ * consumer's own wrapper, a test) behaves like one inside a default grid instead of throwing.
+ */
+const WidgetGridColsContext = createContext<ResolvedCols>({ sm: 2, lg: 2 })
+
+export type WidgetGridProps = BasaltProps & {
+  /** The DESKTOP column count (`lg` and up). Default `2`. Below that the law resolves it: `sm` gets
+   * `min(cols, 2)`, a phone gets 1. Never a responsive object — see the module docblock. */
+  cols?: WidgetGridCols
+  /** The widgets. A plain child takes one column; wrap it in `WidgetGrid.Item` to span more. */
+  children: ReactNode
+}
+
+export function WidgetGrid({ cols = 2, children, className, style }: WidgetGridProps) {
+  const resolved = useMemo<ResolvedCols>(() => ({ sm: Math.min(cols, 2), lg: cols }), [cols])
+
+  return (
+    <WidgetGridColsContext.Provider value={resolved}>
+      <div
+        className={cx(classes.root, className)}
+        data-cols={cols}
+        style={
+          {
+            '--basalt-widget-grid-cols-sm': resolved.sm,
+            '--basalt-widget-grid-cols-lg': resolved.lg,
+            ...style,
+          } as CSSProperties
+        }
+      >
+        {children}
+      </div>
+    </WidgetGridColsContext.Provider>
+  )
+}
+
+export type WidgetGridItemProps = BasaltProps & {
+  /** The DESKTOP span, clamped to the live column count at every narrower breakpoint. Default `1`. */
+  span?: WidgetGridCols
+  /** The one widget this cell holds. */
+  children: ReactNode
+}
+
+/**
+ * One cell of a {@link WidgetGrid}, spanning more than one column. Reached as `WidgetGrid.Item`.
+ */
+function WidgetGridItem({ span = 1, children, className, style }: WidgetGridItemProps) {
+  const cols = useContext(WidgetGridColsContext)
+
+  return (
+    <div
+      className={cx(classes.item, className)}
+      data-span={span}
+      style={
+        {
+          '--basalt-widget-grid-span-sm': Math.min(span, cols.sm),
+          '--basalt-widget-grid-span-lg': Math.min(span, cols.lg),
+          ...style,
+        } as CSSProperties
+      }
+    >
+      {children}
+    </div>
+  )
+}
+
+WidgetGrid.Item = WidgetGridItem

package/src/{widget-header → dashboard}/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.
@@ -221,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/dashboard/widget-header.tsx

@@ -0,0 +1,292 @@
+/**
+ * WidgetHeader — the one heading primitive behind every section, card and table title
+ * (docs/CONTROLS-SPEC.md §2.2, law C8). Plain elements + one CSS module, no `@mantine/*` import
+ * anywhere in this folder, so it can be composed from inside `charts/` without tripping
+ * `basalt/token-layer-boundary` or `check-dist-layering.mjs`.
+ *
+ * `tier: 'section'` renders an `<h2>` at the taller section-header height; `tier: 'widget'`
+ * renders an `<h3>` at the tighter, display-only icon-tier height — both share the same head-font
+ * 88%/550 title treatment. `tier: 'group'` also renders an `<h3>`, but at the quietest rank on the
+ * page: a mono, uppercase, faint micro-label — an inspector/aside group heading, one step below a
+ * `widget` tier and resolved automatically by `Section` when it renders on the `PageAside` panel
+ * surface (never a call-site prop). The title row holds title/icon/info/count/actions only; `value`
+ * + `delta` render on their own hero-metric row directly beneath it, for every tier — never inline
+ * with the title. `StatCard`, `ChartCard`, `Section`, `SettingsSection`/`DangerZone` and
+ * `BasaltDataTable` each compose this and render nothing else above their body (wave 3,
+ * docs/CONTROLS-SPEC.md §2.2's composer table).
+ *
+ * @example
+ * import { WidgetHeader } from 'basalt-ui'
+ *
+ * <WidgetHeader
+ *   tier="widget"
+ *   title="Active Users"
+ *   value="12,483"
+ *   delta={4.2}
+ *   deltaPeriod="MoM"
+ *   actions={<ActionIcon variant="subtle"><IconDots /></ActionIcon>}
+ * />
+ */
+import { useEffect, useId, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
+import { IconSlot } from '../theme/icon-slot'
+import { DeltaBadge } from './delta-badge'
+import type { DeltaPolarity } from './delta-badge'
+import classes from './widget-header.module.css'
+
+export type WidgetHeaderTier = 'section' | 'widget' | 'group'
+
+/**
+ * The four boxes a consumer can reach (`common/props.ts`): `root` is the header stack, `title` is
+ * the heading ELEMENT (`<h2>`/`<h3>`) rather than its row, `metric` is the hero `value`/`unit`/
+ * `delta` row, `icon` is the leading `IconSlot`.
+ *
+ * The other boxes this paints — the title row, the count tag, the actions span, the subtitle, the
+ * sparkline, the info bubble — are deliberately absent. Each is a one-shot readout basalt positions,
+ * not a layout box a consumer places, and `actions`/`sparkline` already take a `ReactNode` the
+ * caller can class itself.
+ */
+export type WidgetHeaderSlot = 'root' | 'title' | 'metric' | 'icon'
+
+export type WidgetHeaderProps = BasaltProps &
+  SlotStylesProps<WidgetHeaderSlot> & {
+    /** `section` renders an `<h2>` at the section-header height; `widget` renders an `<h3>` at the
+     * tighter icon-tier height, display-only; `group` also renders an `<h3>` but as the quietest
+     * heading rank on the page — mono micro uppercase faint, one step below `widget` — for an
+     * inspector/aside group label. `Section` resolves `group` automatically from the enclosing filter
+     * surface; it is never a call-site prop. */
+    tier: WidgetHeaderTier
+    /** Head-font title (88% stretch, weight 550). */
+    title: string
+    /** Optional leading icon, rendered before the title. Decorative — hidden from assistive tech. */
+    icon?: ReactNode
+    /** Optional muted line rendered below the title row. */
+    subtitle?: string
+    /**
+     * Renders an info glyph BESIDE the heading (never inside it — this text would otherwise become
+     * part of the heading's accessible name, and an `info` paragraph read out in every headings list
+     * is what that cost). The glyph is named `More information`; the text itself reaches assistive
+     * tech through `aria-describedby` on a `role="tooltip"` bubble that opens on hover, focus and
+     * click — so a keyboard user gets it too. Mantine-free: a plain state bubble, not a Tooltip.
+     */
+    info?: string
+    /** Pre-formatted metric value (mono, hero size). Renders on its own row with `delta`, directly
+     * under the title row — never inline with the title. */
+    value?: string
+    /**
+     * The value's unit, rendered immediately after it on the hero row: muted, mono, `--vx-text-sm`.
+     *
+     * It exists because `value` is a pre-formatted `string` and a KPI's unit is not part of the
+     * number: `412` and `TSS` are two facts at two weights, and jamming them into one string paints
+     * the unit at the hero's 24px — which reads as a second numeral. `subtitle` was the only place a
+     * unit could go before this, and a unit on its own line under the value is a different claim (the
+     * BASIS: `7-day rolling`), so cards using both had to pick one.
+     *
+     * Never a substitute for the number's own formatting: a thousands separator, a currency symbol or
+     * a `%` belong in `value`, where they are part of how the numeral reads.
+     */
+    unit?: string
+    /** Signed delta rendered via `DeltaBadge`, on the same hero-metric row as `value`. */
+    delta?: number
+    /** Comparison timeframe forwarded to `DeltaBadge` (e.g. `MoM`). */
+    deltaPeriod?: string
+    /** Which sign reads as the good verdict — forwarded to `DeltaBadge`'s `polarity`. Defaults to
+     * `'up-good'` (today's behaviour). See {@link DeltaPolarity}. */
+    deltaPolarity?: DeltaPolarity
+    /**
+     * Formats `delta` into the chip's label — forwarded to `DeltaBadge`'s `format`. Defaults to
+     * `${Math.abs(delta).toFixed(1)}%`.
+     *
+     * It exists because not every delta is a percentage: a pace card's trend is `0:12 /km` and a
+     * throughput card's is `0.3 km/h`, and the default printed both as a percent — a wrong unit on a
+     * KPI, which is worse than no chip. A FUNCTION rather than a label string, so the number stays the
+     * number: `delta` still drives the tone and the glyph, and there is exactly one place the sign is
+     * decided.
+     *
+     * The value arrives SIGNED, so a formatter that wants to print the sign itself (`−0:12 /km`) can —
+     * pair it with `deltaGlyph={false}` so the ▼ does not say the same thing twice.
+     */
+    deltaFormat?: (delta: number) => string
+    /** Render `DeltaBadge`'s ▲/▼ glyph. Defaults to `true`; a zero delta never shows one. Pass
+     * `false` when `deltaFormat` prints the sign itself. */
+    deltaGlyph?: boolean
+    /** Trend visual slot, rendered below the metric row. Carries `data-placement="right"` so a
+     * wave-3 composer's `bleed` layout can select it. */
+    sparkline?: ReactNode
+    /** Mono count tag rendered after the title (C11 — every table/list states its count). `0` is a
+     * real count and renders, distinct from omitting the prop entirely. */
+    count?: number
+    /** Right-aligned slot (`margin-inline-start: auto`) — the C1/C5 home for header actions. */
+    actions?: ReactNode
+  }
+
+/**
+ * The named slices of {@link WidgetHeaderProps} its composers share, and the answer to audit B #2:
+ * four composers exposed four DIFFERENT subsets of the same base through four ad-hoc `Omit`s, so a
+ * consumer moving a KPI from `StatCard` → `ChartCard` → `Section` lost `unit`, `count`,
+ * `deltaFormat` or `deltaGlyph` with no compiler word about it. A slice is a `Pick` with a NAME:
+ * a composer states which slices it re-publishes, and an omission becomes a deliberate, readable
+ * line rather than an accident of whichever props the author happened to remember.
+ *
+ * The three are cut along the three ROWS `WidgetHeader` actually paints — the title row, the hero
+ * metric, and the delta chip on it — so "which slice does this composer take" and "which boxes does
+ * it draw" are the same question.
+ *
+ * Adopted by `StatCard` and `SettingsSection`. `Section` and `ChartCard` still cut their own
+ * subsets; both should compose these instead — the composer table in `docs/CONTROLS-SPEC.md` §2.2
+ * is the ledger of which one takes which.
+ *
+ * The title row: what every composer without exception publishes.
+ */
+export type WidgetHeaderTitleProps = Pick<WidgetHeaderProps, 'title' | 'icon' | 'subtitle' | 'info'>
+
+/**
+ * The hero metric row's value half. `value` is OPTIONAL here because it is on `WidgetHeader`; a
+ * composer whose whole reason to exist is the number (`StatCard`) redeclares it as required.
+ */
+export type WidgetHeaderMetricProps = Pick<WidgetHeaderProps, 'value' | 'unit'>
+
+/**
+ * The delta chip that rides the hero metric row — all five props together, never a subset. Splitting
+ * them is how `deltaFormat` came to type-check on `Section` and render nothing: a composer that
+ * publishes `delta` and not its formatter prints a percent sign over a pace.
+ */
+export type WidgetHeaderDeltaProps = Pick<
+  WidgetHeaderProps,
+  'delta' | 'deltaPeriod' | 'deltaPolarity' | 'deltaFormat' | 'deltaGlyph'
+>
+
+/**
+ * The info affordance. A `title` attribute alone was never enough — it renders on hover only, so a
+ * keyboard user focusing the glyph saw nothing at all. This is the bubble `ChartCard` used to own
+ * before it composed `WidgetHeader`, moved down here so every tier gets the same behaviour:
+ * opens on hover/focus/click, closes on leave/blur/Escape/outside pointer-down, and is wired to the
+ * trigger with `aria-describedby` only while open.
+ *
+ * Exported from the MODULE but deliberately not from `src/widget-header/index.ts`: it is not a
+ * public primitive, it is the one info affordance basalt draws, and `controls/panel-row.tsx`
+ * composes it so an inspector row's `hint` is the same glyph, bubble and keyboard behaviour a
+ * `WidgetHeader`'s `info` is — not a second one that drifts.
+ */
+export function InfoGlyph({ text }: { text: 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 className={classes.info}>
+      <button
+        ref={triggerRef}
+        type="button"
+        className={classes.infoTrigger}
+        // The GLYPH is named, not the text — `text` reaches AT through `aria-describedby` below, so
+        // it never lands in the heading's or the button's accessible name.
+        aria-label="More information"
+        aria-describedby={open ? tipId : undefined}
+        data-open={open}
+        onMouseEnter={() => setOpen(true)}
+        onMouseLeave={() => setOpen(false)}
+        onFocus={() => setOpen(true)}
+        onBlur={() => setOpen(false)}
+        onClick={() => setOpen(true)}
+        onKeyDown={(event) => {
+          if (event.key === 'Escape') setOpen(false)
+        }}
+      >
+        <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" className={classes.infoBubble}>
+          {text}
+        </span>
+      )}
+    </span>
+  )
+}
+
+export function WidgetHeader({
+  tier,
+  title,
+  icon,
+  subtitle,
+  info,
+  value,
+  unit,
+  delta,
+  deltaPeriod,
+  deltaPolarity,
+  deltaFormat,
+  deltaGlyph,
+  sparkline,
+  count,
+  actions,
+  className,
+  style,
+  classNames,
+}: WidgetHeaderProps) {
+  const Heading = tier === 'section' ? 'h2' : 'h3'
+
+  return (
+    <div
+      className={cx(classes.root, classNames?.root, className)}
+      data-tier={tier}
+      {...(style !== undefined && { style })}
+    >
+      <div className={classes.titleRow}>
+        <Heading className={cx(classes.heading, classNames?.title)}>
+          {/* `IconSlot` owns the box; the TIER owns its size, through the
+              `--vx-space-icon-size` this module sets per `data-tier`. So a `tier="widget"`
+              heading draws 14px and a `tier="section"` heading 16px with no prop and no
+              per-component `> svg` rule — see `theme/icon-slot.tsx`. */}
+          {icon !== undefined && (
+            <IconSlot className={cx(classes.icon, classNames?.icon)}>{icon}</IconSlot>
+          )}
+          <span className={classes.titleText}>{title}</span>
+        </Heading>
+        {/* OUTSIDE the heading on purpose — see `info`'s own doc. */}
+        {info !== undefined && <InfoGlyph text={info} />}
+        {count !== undefined && <span className={classes.count}>{count}</span>}
+        {actions !== undefined && <span className={classes.actions}>{actions}</span>}
+      </div>
+      {(value !== undefined || delta !== undefined) && (
+        <div className={cx(classes.metrics, classNames?.metric)}>
+          {value !== undefined && <span className={classes.value}>{value}</span>}
+          {/* Gated on `value`, not on itself: a unit with nothing to qualify is a stray word, and a
+              card that lost its number must not keep printing `TSS` beside the empty space. */}
+          {value !== undefined && unit !== undefined && (
+            <span className={classes.unit}>{unit}</span>
+          )}
+          {delta !== undefined && (
+            <DeltaBadge
+              value={delta}
+              period={deltaPeriod}
+              {...(deltaPolarity !== undefined && { polarity: deltaPolarity })}
+              {...(deltaFormat !== undefined && { format: deltaFormat })}
+              {...(deltaGlyph !== undefined && { withGlyph: deltaGlyph })}
+            />
+          )}
+        </div>
+      )}
+      {subtitle !== undefined && <span className={classes.subtitle}>{subtitle}</span>}
+      {sparkline !== undefined && (
+        <div className={classes.sparkline} data-placement="right">
+          {sparkline}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/data/data-table.module.css

@@ -0,0 +1,64 @@
+/*
+ * BasaltDataTable — the two boxes the base Mantine `Table` cannot paint from a prop: an activatable
+ * row, and the bulk-action bar a selection raises.
+ */
+
+/*
+ * `onRowActivate` — the row → detail hook that pairs with `PageAside`. The row keeps its native
+ * `<tr>` semantics and takes `tabIndex=0` + `data-activatable` rather than `role="button"`: a role
+ * swap would take the row OUT of the table's own row/cell semantics, so a screen reader would stop
+ * announcing the column headers with each cell — which is the whole reason the data is in a table.
+ * The affordance is therefore the cursor and the focus ring, not a role.
+ */
+.activatable {
+  cursor: pointer;
+}
+
+.activatable:focus-visible {
+  outline: 2px solid var(--vx-accent);
+  outline-offset: -2px;
+}
+
+/*
+ * The bulk bar. It sits between the header row and the table, and it is a SURFACE rather than a
+ * bare row: it appears and disappears with the selection, so without a background it reads as the
+ * table jumping. `--vx-surface-subtle` is the same one-step-up fill the sheet rows and the sidebar
+ * use, so nothing new is introduced to the page's surface ladder.
+ */
+.bulkBar {
+  padding: var(--vx-space-row-inset-y, 0.375rem) var(--vx-space-row-inset-x, 0.5rem);
+  border: 1px solid var(--vx-surface-hairline);
+  border-radius: var(--vx-radius-ctrl);
+  background: var(--vx-surface-subtle);
+}
+
+/*
+ * The count. Mono/micro, the same numeric readout idiom the pagination bar's range label uses
+ * (`docs/DESIGN-SPEC.md` §3) — a selection count is a figure, and reading it in the proportional
+ * body font beside proportional button labels made the bar read as a sentence.
+ */
+.bulkCount {
+  font-family: var(--mantine-font-family-monospace);
+  font-size: var(--vx-text-xs);
+  font-variant-numeric: tabular-nums;
+  color: var(--vx-muted);
+}
+
+/*
+ * The measured containment wrapper — `stickyHeader` with neither `maxHeight` nor `minWidth`, the
+ * one shape whose overflow mode cannot be decided statically. `useMeasuredContainment`
+ * (`data-table.tsx`) writes `data-contained`; the two states are declared here rather than as an
+ * inline style so the flip is a single attribute write and a reader can see both at once.
+ *
+ * `[data-contained='false']` is deliberately NOT `overflow: visible` — it is the absence of any
+ * overflow declaration, because `overflow-x: visible` beside a computed `overflow-y` is exactly
+ * the pairing the browser rewrites to `auto`. `min-width: 0` is the flex/grid floor every
+ * containing chain in this library needs and none of them get by default.
+ */
+.containment {
+  min-width: 0;
+}
+
+.containment[data-contained='true'] {
+  overflow-x: auto;
+}

package/src/data/data-table.module.css.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 activatable: string
+  readonly bulkBar: string
+  readonly bulkCount: string
+  readonly containment: string
+}
+export default classes