basalt-ui 1.25.0 → 1.27.0

package/src/dashboard/delta-badge.tsx

@@ -1,76 +1,6 @@
 /**
- * DeltaBadge — the KPI trend chip (docs/DESIGN-SPEC.md §5): mono 11.5px weight 600, status-color
- * text on a status-13% tint, radius 6, 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).
- *
- * @example
- * import { DeltaBadge } from 'basalt-ui'
- *
- * <DeltaBadge value={12.4} />                          // ▲ 12.4%, success tint
- * <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` moved to `src/widget-header/` (docs/CONTROLS-SPEC.md §2.2) so `WidgetHeader` can
+ * compose it Mantine-free. Re-exported here unchanged so this deep import path — and `StatCard`'s
+ * own `./delta-badge` import — keep working without a wave-3 edit.
  */
-import { Badge } from '@mantine/core'
-import { alpha, VX } from '../tokens'
-
-export type DeltaBadgeProps = {
-  /** Signed delta driving tone (positive/negative/zero) and, by default, the label magnitude. */
-  value: number
-  /** 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. */
-  withGlyph?: boolean
-  /** Optional comparison timeframe rendered directly after the value in a dimmer shade of the same
-   * tone (e.g. `MoM`, `WoW`, `YTD`) — states what the delta is measured against without a hover. */
-  period?: string | undefined
-}
-
-const defaultFormat = (value: number): string => `${Math.abs(value).toFixed(1)}%`
-
-export function DeltaBadge({
-  value,
-  format = defaultFormat,
-  withGlyph = true,
-  period,
-}: DeltaBadgeProps) {
-  const tone = value > 0 ? VX.status.good : value < 0 ? VX.status.bad : VX.faint
-  const glyph = value > 0 ? '▲' : value < 0 ? '▼' : undefined
-  const showGlyph = withGlyph && glyph !== undefined
-
-  return (
-    <Badge
-      styles={{
-        root: {
-          backgroundColor: alpha(tone, 0.13),
-          padding: 'var(--vx-space-badge-inset-y) var(--vx-space-badge-inset-x)',
-          height: 'auto',
-        },
-        label: {
-          display: 'inline-flex', // theme-allow inline-display — a Badge `styles.label` part, not a layout node Flex could replace
-          alignItems: 'center',
-          gap: 3, // theme-allow inline-spacing — sub-scale glyph-to-label gap, below the smallest scale stop
-          fontFamily: 'var(--basalt-font-mono)',
-          fontSize: VX.text.xs,
-          fontWeight: 600,
-          textTransform: 'none',
-          letterSpacing: 'normal',
-          color: tone,
-        },
-      }}
-    >
-      {/* optical glyph ratio relative to the label, not a scale step */}
-      {showGlyph && <span style={{ fontSize: '0.8em' }}>{glyph}</span>}
-      {format(value)}
-      {period && (
-        <span
-          style={{ marginLeft: 4, fontWeight: 500, opacity: 0.6 }} // theme-allow inline-spacing — sub-scale optical period offset, below the smallest scale stop
-        >
-          {period}
-        </span>
-      )}
-    </Badge>
-  )
-}
+export { DeltaBadge, type DeltaBadgeProps } from '../widget-header/delta-badge'

package/src/dashboard/index.ts

@@ -1,5 +1,10 @@
 export { DeltaBadge, type DeltaBadgeProps } from './delta-badge'
-export { StatCard, type StatCardProps, type StatCardTone } from './stat-card'
+export {
+  StatCard,
+  type StatCardBreakdownRow,
+  type StatCardProps,
+  type StatCardTone,
+} from './stat-card'
 export { EmptyState, type EmptyStateProps } from './empty-state'
 export {
   SettingsSection,

package/src/dashboard/settings-section.module.css

@@ -3,6 +3,16 @@
  * vertical padding and a 1px `--vx-divider` rule below it, EXCEPT the last row in the section —
  * `:not(:last-child)` strips the divider there so the section doesn't end on a trailing line.
  */
+
+/* The WidgetHeader block (plus DangerZone's eyebrow, when present) sits above `.rows` with the
+ * same gap the old inline `Stack gap={2} mb="sm"` produced. */
+.header {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-bottom: var(--mantine-spacing-sm);
+}
+
 .rows > * {
   padding: var(--vx-space-settings-row-inset-y) 0;
 }

package/src/dashboard/settings-section.module.css.d.ts

@@ -3,6 +3,7 @@
  * signature — so dot access stays verbatim under the package's strict flags.
  */
 declare const classes: {
+  readonly header: string
   readonly rows: string
   readonly row: string
   readonly control: string

package/src/dashboard/settings-section.test.tsx

@@ -0,0 +1,56 @@
+/**
+ * SettingsSection / DangerZone — the WidgetHeader composition (docs/CONTROLS-SPEC.md §2.2):
+ * `description` renamed to `subtitle`, both now render an h2 (`tier="section"`) via `WidgetHeader`,
+ * and `actions` reaches the header's actions slot.
+ */
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import type { ReactElement } from 'react'
+import { DangerZone, SettingsSection } from './settings-section'
+
+function renderWith(node: ReactElement) {
+  return render(<MantineProvider>{node}</MantineProvider>)
+}
+
+describe('SettingsSection composes WidgetHeader at the section tier', () => {
+  test('renders an h2 carrying the title', () => {
+    renderWith(
+      <SettingsSection title="Profile">
+        <div>rows</div>
+      </SettingsSection>,
+    )
+    expect(screen.getByRole('heading', { level: 2, name: 'Profile' })).toBeDefined()
+  })
+
+  test('subtitle (renamed from description) renders below the title', () => {
+    renderWith(
+      <SettingsSection title="Profile" subtitle="Your public identity.">
+        <div>rows</div>
+      </SettingsSection>,
+    )
+    expect(screen.getByText('Your public identity.')).toBeDefined()
+  })
+
+  test('actions reach the header actions slot', () => {
+    renderWith(
+      <SettingsSection title="Profile" actions={<button type="button">Export</button>}>
+        <div>rows</div>
+      </SettingsSection>,
+    )
+    expect(screen.getByRole('button', { name: 'Export' })).toBeDefined()
+  })
+})
+
+describe('DangerZone keeps its eyebrow alongside the WidgetHeader', () => {
+  test('renders the eyebrow and an h2 title', () => {
+    renderWith(
+      <DangerZone title="Delete workspace" subtitle="This action cannot be undone.">
+        <div>rows</div>
+      </DangerZone>,
+    )
+    expect(screen.getByText('Danger Zone')).toBeDefined()
+    expect(screen.getByRole('heading', { level: 2, name: 'Delete workspace' })).toBeDefined()
+    expect(screen.getByText('This action cannot be undone.')).toBeDefined()
+  })
+})

package/src/dashboard/settings-section.tsx

@@ -1,15 +1,18 @@
 /**
  * SettingsSection / SettingsRow / DangerZone — the settings-page building blocks
- * (docs/DESIGN-SPEC.md §5). A `SettingsSection` is a titled card grouping a stack of
- * `SettingsRow`s, each separated by a 1px `--vx-divider` rule (no border on the last row —
- * handled by the shared `.rows` container in `settings-section.module.css`). `DangerZone` is a
- * `SettingsSection` variant for irreversible actions: a mono "DANGER ZONE" eyebrow in
+ * (docs/DESIGN-SPEC.md §5, docs/CONTROLS-SPEC.md §2.2). A `SettingsSection` is a titled card
+ * grouping a stack of `SettingsRow`s, each separated by a 1px `--vx-divider` rule (no border on the
+ * last row — handled by the shared `.rows` container in `settings-section.module.css`). `DangerZone`
+ * is a `SettingsSection` variant for irreversible actions: a mono "DANGER ZONE" eyebrow in
  * status-danger, and a danger-tinted ring layered atop the card's shadow-card depth.
  *
+ * Both compose `WidgetHeader tier="section"` for the title/subtitle/actions row — `actions` is
+ * wrapped in `CtlSlot` (C1/C5).
+ *
  * @example
  * import { SettingsSection, SettingsRow, DangerZone } from 'basalt-ui'
  *
- * <SettingsSection title="Profile" description="Your public identity.">
+ * <SettingsSection title="Profile" subtitle="Your public identity.">
  *   <SettingsRow label="Display name" control={<TextInput value={name} onChange={...} />} />
  *   <SettingsRow
  *     label="Email"
@@ -18,7 +21,7 @@
  *   />
  * </SettingsSection>
  *
- * <DangerZone title="Delete workspace" description="This action cannot be undone.">
+ * <DangerZone title="Delete workspace" subtitle="This action cannot be undone.">
  *   <SettingsRow
  *     label="Delete this workspace"
  *     control={<Button color="red" variant="outline">Delete</Button>}
@@ -27,17 +30,11 @@
  */
 import { Card, Stack } from '@mantine/core'
 import type { ReactNode } from 'react'
+import { WidgetHeader } from '../widget-header'
+import { CtlSlot } from '../theme'
 import { alpha, VX } from '../tokens'
 import classes from './settings-section.module.css'
 
-const titleStyle = {
-  fontFamily: 'var(--basalt-font-head)',
-  fontStretch: '88%' as const,
-  fontSize: VX.text.md,
-  fontWeight: 550,
-  color: VX.ink,
-}
-
 const eyebrowStyle = {
   fontFamily: 'var(--basalt-font-mono)',
   fontSize: VX.text.micro,
@@ -48,23 +45,27 @@ const eyebrowStyle = {
 }
 
 export type SettingsSectionProps = {
-  /** Head-font section title (15px, weight 550, ink). */
+  /** Head-font section title, rendered via `WidgetHeader tier="section"`. */
   title: string
   /** Optional 13px muted description below the title. */
-  description?: string
+  subtitle?: string
+  /** Header-right slot — wrapped in `CtlSlot` (C1/C5). */
+  actions?: ReactNode
   /** Section body — typically a stack of `SettingsRow`s. */
   children: ReactNode
 }
 
-export function SettingsSection({ title, description, children }: SettingsSectionProps) {
+export function SettingsSection({ title, subtitle, actions, children }: SettingsSectionProps) {
   return (
     <Card style={{ padding: 'var(--mantine-spacing-xs) var(--mantine-spacing-sm)' }}>
-      <Stack gap={2} mb="sm">
-        <span style={titleStyle}>{title}</span>
-        {description && (
-          <span style={{ fontSize: VX.text.sm, color: VX.muted }}>{description}</span>
-        )}
-      </Stack>
+      <div className={classes.header}>
+        <WidgetHeader
+          tier="section"
+          title={title}
+          {...(subtitle !== undefined && { subtitle })}
+          {...(actions !== undefined && { actions: <CtlSlot>{actions}</CtlSlot> })}
+        />
+      </div>
       <div className={classes.rows}>{children}</div>
     </Card>
   )
@@ -97,7 +98,7 @@ export function SettingsRow({ label, description, control, children }: SettingsR
 
 export type DangerZoneProps = SettingsSectionProps
 
-export function DangerZone({ title, description, children }: DangerZoneProps) {
+export function DangerZone({ title, subtitle, actions, children }: DangerZoneProps) {
   return (
     <Card
       style={{
@@ -105,13 +106,15 @@ export function DangerZone({ title, description, children }: DangerZoneProps) {
         boxShadow: `${VX.shadowCard}, 0 0 0 1px ${alpha(VX.status.bad, 0.25)}`,
       }}
     >
-      <Stack gap={2} mb="sm">
+      <div className={classes.header}>
         <span style={eyebrowStyle}>Danger Zone</span>
-        <span style={titleStyle}>{title}</span>
-        {description && (
-          <span style={{ fontSize: VX.text.sm, color: VX.muted }}>{description}</span>
-        )}
-      </Stack>
+        <WidgetHeader
+          tier="section"
+          title={title}
+          {...(subtitle !== undefined && { subtitle })}
+          {...(actions !== undefined && { actions: <CtlSlot>{actions}</CtlSlot> })}
+        />
+      </div>
       <div className={classes.rows}>{children}</div>
     </Card>
   )

package/src/dashboard/stat-card.module.css

@@ -0,0 +1,153 @@
+/*
+ * StatCard's sparkline placement (docs/CONTROLS-SPEC.md §2.2). `bleed` (default) keeps the historic
+ * full-width row beneath the hero value, bled past the card's own inset padding — same negative
+ * margins the pre-WidgetHeader version drew inline. `right` sits the sparkline beside the
+ * `WidgetHeader`'s hero-value row instead, the reference-design look, and collapses back to
+ * `bleed`'s stacked layout below `sm` — CSS only, no JS branch (`47.99375em` is Mantine's own
+ * complement of `min-width: 48em`, same value `content/prose.module.css` derives it from).
+ */
+
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stat-card-gap);
+  height: 100%;
+}
+
+/*
+ * `flex-end`, not `center`: the sparkline belongs to the HERO ROW, and the hero row is the header
+ * block's last line. Centred against the whole body it floated between the title and the value,
+ * which reads as a third, unrelated element; bottom-aligned to the header block it sits beside the
+ * number it describes, the reference layout. `gap` is the card's own control gap so the trend never
+ * touches a long value.
+ */
+.body[data-placement='right'] {
+  flex-direction: row;
+  align-items: flex-end;
+  gap: var(--vx-space-control-gap);
+}
+
+.header {
+  min-width: 0;
+}
+
+/*
+ * `flex-shrink: 0` on the header, `1` on the sparkline slot below: the hero value and its delta keep
+ * their width and the TREND gives ground. The other way round, a 4-up KPI grid on a 1440 viewport
+ * ellipsized `$1,294,900` to `$1294.…` in order to keep 72px of bars intact, which is the wrong
+ * thing to protect. The value still carries `overflow: hidden` as the last resort, and `Card` clips.
+ */
+.body[data-placement='right'] .header {
+  flex: 1 0 auto;
+  min-width: 0;
+}
+
+/*
+ * The `breakdown` rows — the two or three parts a hero number is made of, under it.
+ *
+ * NO hairline, anywhere in this block, and that is a law rather than a taste: `docs/CONTROLS-SPEC.md`
+ * §2.1 puts a horizontal rule between OPTION rows and nowhere else, and `theme/divider-law.test.ts`
+ * inventories every one basalt draws. Three rules inside a KPI card would read as a table wearing a
+ * card's clothes. The rows are separated by the stack rhythm and by weight — a muted label against
+ * an ink value — which is the same separation the sheet's own field groups use.
+ */
+.breakdown {
+  display: flex;
+  flex-direction: column;
+  margin: var(--vx-space-stack-sm) 0 0;
+  padding: 0;
+  min-width: 0;
+}
+
+/*
+ * One row, one line, at the TAG tier (`controlHeightTag`, 20px at level 0) — the smallest control
+ * step basalt declares, and a token rather than a literal so the rows track the density knob with
+ * everything else. `justify-content: space-between` is what makes the pair read as a row without a
+ * grid: the label leads, the value trails, and neither needs a column to align against because
+ * every row in one card is the same box.
+ */
+.breakdownRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--vx-space-control-gap);
+  min-height: var(--vx-space-control-height-tag);
+  min-width: 0;
+}
+
+.breakdownLabel {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--vx-text-sm);
+  color: var(--vx-muted);
+}
+
+/* Mono and ink — a breakdown value is a number, and it is the half of the row worth reading. Never
+ * shrinks: the LABEL is the prose half and the one that may ellipsize. */
+.breakdownValue {
+  flex-shrink: 0;
+  margin: 0;
+  font-family: var(--basalt-font-mono);
+  font-size: var(--vx-text-sm);
+  font-weight: 500;
+  color: var(--vx-ink);
+}
+
+/*
+ * A row past a threshold. Same vocabulary and the same per-scheme solids as the card's own tone rail
+ * (`stat-card.tsx`'s `VX.status[tone]`), so a row saying `bad` and a rail saying `bad` are one claim
+ * at two scales. Colour is not the only carrier at the CARD level (the rail ships a
+ * `VisuallyHidden` verdict); at the ROW level the label is the carrier — a row reading
+ * `Paid · 1,204` states its own subject either way, and the tint only ranks it.
+ */
+.breakdownRow[data-tone='good'] .breakdownValue {
+  color: var(--vx-status-good);
+}
+
+.breakdownRow[data-tone='warn'] .breakdownValue {
+  color: var(--vx-status-warn);
+}
+
+.breakdownRow[data-tone='bad'] .breakdownValue {
+  color: var(--vx-status-bad);
+}
+
+.sparklineBleed {
+  margin-top: auto;
+  margin-inline: calc(-1 * var(--mantine-spacing-sm));
+  margin-bottom: calc(-1 * var(--mantine-spacing-xs));
+}
+
+/* Asks for `StatCard`'s `SPARKLINE_RIGHT_WIDTH`/`_HEIGHT` (handed down as custom properties, so this
+ * rule and the `< sm` reset below can both reach them) and shrinks below the width before the hero
+ * row does — see the `.header` note above. `min-width: 0` is what lets it. */
+.sparklineRight {
+  display: flex;
+  flex: 0 1 var(--basalt-stat-sparkline-w, 4.5rem);
+  min-width: 0;
+  height: var(--basalt-stat-sparkline-h, 1.625rem);
+  align-items: flex-end;
+  overflow: hidden;
+}
+
+@media (max-width: 47.99375em) {
+  .body[data-placement='right'] {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .body[data-placement='right'] .header {
+    flex: initial;
+  }
+
+  /* The row became a COLUMN, so `flex-basis` is now the main-axis HEIGHT — the 72px width would
+   * become a 72px-tall box around 26px of bars. `flex: none` + the height keeps the bled trend the
+   * same 26px it is beside a hero row. */
+  .body[data-placement='right'] .sparklineRight {
+    flex: none;
+    margin-top: auto;
+    margin-inline: calc(-1 * var(--mantine-spacing-sm));
+    margin-bottom: calc(-1 * var(--mantine-spacing-xs));
+  }
+}

package/src/dashboard/stat-card.module.css.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 body: string
+  readonly header: string
+  readonly breakdown: string
+  readonly breakdownRow: string
+  readonly breakdownLabel: string
+  readonly breakdownValue: string
+  readonly sparklineBleed: string
+  readonly sparklineRight: string
+}
+export default classes