basalt-ui 1.24.0 → 1.26.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/query-state.tsx

@@ -26,7 +26,7 @@ export type QueryStateVariant = 'page' | 'section'
  * The structural subset of a TanStack `UseQueryResult` these components read.
  *
  * Typed as a SUBSET rather than as `UseQueryResult<T>` on purpose: a composed, derived or
- * hand-rolled result must be passable without a cast (3 of image-share's 10 call sites are), and
+ * hand-rolled result must be passable without a cast, and
  * these components stay independent of which `@tanstack/react-query` major a consumer pins. This
  * is NOT a claim that the root barrel is free of that package — `./connectivity` imports
  * `onlineManager` as a value and is re-exported from `src/index.ts`. The cost of the subset is

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,82 @@
+/*
+ * 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;
+}
+
+.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,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 body: string
+  readonly header: string
+  readonly sparklineBleed: string
+  readonly sparklineRight: string
+}
+export default classes

package/src/dashboard/stat-card.test.tsx

@@ -30,7 +30,7 @@ function render(tone?: StatCardTone) {
     <MantineProvider>
       {/* exactOptionalPropertyTypes forbids an explicit tone={undefined} — spread only when set */}
       <StatCard
-        label="Downtime · last 24h"
+        title="Downtime · last 24h"
         value="0 min"
         {...(tone !== undefined ? { tone } : {})}
       />
@@ -86,3 +86,69 @@ describe('omitting tone is not "good" — it is untinted, and says nothing', ()
     expect(markup).toContain('0 min')
   })
 })
+
+describe('the header composes WidgetHeader at the widget tier', () => {
+  test('renders an h3 carrying the title', () => {
+    const markup = renderToStaticMarkup(
+      <MantineProvider>
+        <StatCard title="Active Users" value="12,483" />
+      </MantineProvider>,
+    )
+    expect(markup).toContain('<h3')
+    expect(markup).toContain('Active Users')
+  })
+})
+
+describe('info and subtitle reach the composed WidgetHeader', () => {
+  function renderHeader(props: { info?: string; subtitle?: string }) {
+    return renderToStaticMarkup(
+      <MantineProvider>
+        <StatCard title="Training load" value="412" {...props} />
+      </MantineProvider>,
+    )
+  }
+
+  test('the subtitle renders as its own line under the hero row', () => {
+    expect(renderHeader({ subtitle: 'TSS · 7-day rolling' })).toContain('TSS · 7-day rolling')
+  })
+
+  test('the info text ships with the glyph, and never inside the heading', () => {
+    const markup = renderHeader({ info: 'Sum of per-session TSS over 7 days.' })
+    // `WidgetHeader` renders the bubble only while open, so the closed markup carries the named
+    // trigger — what matters here is that the card FORWARDED the prop and that the text stayed OUT
+    // of the `<h3>`, which is what an `info` rendered inside the heading would silently do.
+    expect(markup).toContain('aria-label="More information"')
+    const heading = /<h3[^>]*>(.*?)<\/h3>/.exec(markup)?.[1] ?? ''
+    expect(heading).toContain('Training load')
+    expect(heading).not.toContain('Sum of')
+  })
+
+  test('neither prop renders anything when omitted — no glyph, no empty line', () => {
+    expect(renderHeader({})).not.toContain('More information')
+  })
+})
+
+describe('sparklinePlacement', () => {
+  function renderWithSparkline(placement?: 'bleed' | 'right') {
+    return renderToStaticMarkup(
+      <MantineProvider>
+        <StatCard
+          title="Active Users"
+          value="12,483"
+          sparkline={<span data-testid="spark">spark</span>}
+          {...(placement !== undefined ? { sparklinePlacement: placement } : {})}
+        />
+      </MantineProvider>,
+    )
+  }
+
+  test('defaults to bleed — the full-width row bled to the card edges', () => {
+    const markup = renderWithSparkline()
+    expect(markup).toContain('data-placement="bleed"')
+  })
+
+  test('right sits the sparkline beside the hero-value row', () => {
+    const markup = renderWithSparkline('right')
+    expect(markup).toContain('data-placement="right"')
+  })
+})