@lovett/ui 0.0.11 → 0.2.0

package/src/__tests__/sparkline.test.tsx

@@ -0,0 +1,368 @@
+/**
+ * Sparkline — ADR-146 D5.
+ *
+ * Two things drive the shape of this file.
+ *
+ * **It must hold at both ends of its size range.** A sparkline that looks
+ * right at 300×60 and clips its end dot at 60×20 is broken in exactly the
+ * place it is actually used — a table cell. So the geometry cases run at both
+ * sizes and assert that no mark leaves the box.
+ *
+ * **It inherits arithmetic from the primitive it supersedes.** The bar
+ * variant reproduces `allocation-sparkbar.tsx:48`'s `8 + (v/max) * (h - 12)`
+ * exactly at that file's 36px default height. That equivalence is the whole
+ * reason the migration in ADR-146 D13 is a swap rather than a redesign, so it
+ * is pinned to the integer.
+ *
+ * Float comparisons use an epsilon (CLAUDE.md §7); the 36px cases land on
+ * integers by construction and are asserted exactly.
+ */
+import { describe, expect, it } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { Sparkline } from '../sparkline'
+
+const EPS = 1e-6
+
+/** The reserved plot box. */
+function plot(container: HTMLElement): HTMLElement {
+  const el = container.querySelector<HTMLElement>('.relative')
+  if (el === null) throw new Error('no plot box rendered')
+  return el
+}
+
+/** The absolutely-positioned bars, left to right. */
+function bars(container: HTMLElement): HTMLElement[] {
+  return Array.from(container.querySelectorAll<HTMLElement>('.relative > div'))
+}
+
+/** A style length as a number, e.g. `'17.5px'` → `17.5`. */
+function px(value: string): number {
+  return Number.parseFloat(value)
+}
+
+describe('Sparkline reserved space', () => {
+  it('reserves its exact box at cell size and at panel size', () => {
+    const { container, rerender } = render(<Sparkline values={[1, 2, 3]} width={60} height={20} />)
+    expect(plot(container)).toHaveStyle({ width: '60px', height: '20px' })
+
+    rerender(<Sparkline values={[1, 2, 3]} width={300} height={60} />)
+    expect(plot(container)).toHaveStyle({ width: '300px', height: '60px' })
+  })
+
+  it('keeps the box when there is no data, so a row cannot reflow', () => {
+    const { container } = render(<Sparkline values={[]} width={60} height={20} />)
+    expect(plot(container)).toHaveStyle({ width: '60px', height: '20px' })
+    expect(container.querySelector('svg')).toBeNull()
+  })
+
+  it('reserves the trailing value column', () => {
+    const { container } = render(<Sparkline values={[1, 2]} valueLabel="11,227" />)
+    const value = container.querySelector<HTMLElement>('span')
+    expect(value).toHaveTextContent('11,227')
+    expect(value).toHaveClass('tabular-nums')
+    expect(value?.style.minWidth).toBe('var(--space-10)')
+  })
+})
+
+describe('Sparkline line variant', () => {
+  it('draws a bare trend — no axes, no gridlines, no frame', () => {
+    const { container } = render(<Sparkline values={[1, 4, 2, 5]} />)
+    const svg = container.querySelector('svg')
+    expect(svg?.querySelectorAll('line')).toHaveLength(0)
+    expect(svg?.querySelectorAll('rect')).toHaveLength(0)
+    expect(svg?.querySelectorAll('text')).toHaveLength(0)
+    // A path for the line, plus the single end dot. Nothing else.
+    expect(svg?.querySelectorAll('path')).toHaveLength(1)
+    expect(svg?.querySelectorAll('circle')).toHaveLength(1)
+  })
+
+  it('plots the exact path at 60x20', () => {
+    const { container } = render(<Sparkline values={[0, 1]} width={60} height={20} />)
+    // dot r 2.5 + half its 1.5 stroke = 3.25 inset on every side.
+    expect(container.querySelector('path')?.getAttribute('d')).toBe('M3.25,16.75 L56.75,3.25')
+  })
+
+  it('plots the exact path at 300x60', () => {
+    const { container } = render(<Sparkline values={[0, 1]} width={300} height={60} />)
+    // dot r 6 + half its 3px stroke = 7.5 inset.
+    expect(container.querySelector('path')?.getAttribute('d')).toBe('M7.5,52.5 L292.5,7.5')
+  })
+
+  it('never lets the end dot leave the box, at either size', () => {
+    for (const [w, h] of [
+      [60, 20],
+      [300, 60],
+    ] as const) {
+      const { container, unmount } = render(<Sparkline values={[0, 1]} width={w} height={h} />)
+      const dot = container.querySelector('circle')
+      const cx = Number(dot?.getAttribute('cx'))
+      const cy = Number(dot?.getAttribute('cy'))
+      const r = Number(dot?.getAttribute('r'))
+      const half = Number(dot?.getAttribute('stroke-width')) / 2
+      expect(cx - r - half).toBeGreaterThanOrEqual(-EPS)
+      expect(cx + r + half).toBeLessThanOrEqual(w + EPS)
+      expect(cy - r - half).toBeGreaterThanOrEqual(-EPS)
+      expect(cy + r + half).toBeLessThanOrEqual(h + EPS)
+      unmount()
+    }
+  })
+
+  it('draws the end dot HOLLOW — surface fill, coloured stroke', () => {
+    const { container } = render(<Sparkline values={[1, 2]} />)
+    const dot = container.querySelector('circle')
+    expect(dot?.getAttribute('fill')).toBe('rgb(var(--surface-card))')
+    expect(dot?.getAttribute('stroke')).toBe('rgb(var(--accent))')
+    expect(Number(dot?.getAttribute('stroke-width'))).toBeGreaterThanOrEqual(1.5)
+  })
+
+  it('drops the dot, and its inset, when emphasis is off', () => {
+    const { container } = render(
+      <Sparkline values={[0, 1]} width={60} height={20} emphasizeLast={false} />,
+    )
+    expect(container.querySelector('circle')).toBeNull()
+    // Inset is now half the 2px stroke, so the line spans nearly the full box.
+    expect(container.querySelector('path')?.getAttribute('d')).toBe('M1,19 L59,1')
+  })
+
+  it('insets for a thick stroke even when the dot reserves less', () => {
+    // strokeWidth 8 at h=20 needs 4px of inset; the dot only reserves 3.25.
+    // Taking the max is what keeps the line inside the viewBox.
+    const { container } = render(
+      <Sparkline values={[0, 1]} width={60} height={20} strokeWidth={8} />,
+    )
+    const d = container.querySelector('path')?.getAttribute('d') ?? ''
+    const ys = [...d.matchAll(/,(-?[\d.]+)/g)].map((m) => Number(m[1]))
+    for (const y of ys) {
+      expect(y).toBeGreaterThanOrEqual(4 - EPS)
+      expect(y).toBeLessThanOrEqual(20 - 4 + EPS)
+    }
+  })
+
+  it('emphasizes the peak rather than the last point when asked', () => {
+    const { container } = render(
+      <Sparkline values={[0, 9, 1]} width={300} height={60} emphasisIndex={1} />,
+    )
+    expect(Number(container.querySelector('circle')?.getAttribute('cx'))).toBeCloseTo(150, 6)
+  })
+
+  it('clamps an out-of-range emphasis index onto a real mark', () => {
+    const { container } = render(
+      <Sparkline values={[0, 1, 2]} width={300} height={60} emphasisIndex={99} />,
+    )
+    expect(Number(container.querySelector('circle')?.getAttribute('cx'))).toBeCloseTo(292.5, 6)
+  })
+
+  it('adds the area fill only when asked, and only as a tint', () => {
+    const { container, rerender } = render(<Sparkline values={[1, 2, 3]} />)
+    expect(container.querySelectorAll('path')).toHaveLength(1)
+
+    rerender(<Sparkline values={[1, 2, 3]} area />)
+    const paths = container.querySelectorAll('path')
+    expect(paths).toHaveLength(2)
+    expect(paths[0]?.getAttribute('fill-opacity')).toBe('0.12')
+    expect(paths[0]?.getAttribute('fill')).toBe('rgb(var(--accent))')
+  })
+
+  it('colours from the frozen series lookup when given a slot', () => {
+    const { container } = render(<Sparkline values={[1, 2]} slot={2} />)
+    expect(container.querySelector('path')?.getAttribute('stroke')).toBe('rgb(var(--series-3))')
+  })
+})
+
+describe('Sparkline line degenerate data', () => {
+  it('paints a single datum as a dot rather than nothing', () => {
+    const { container } = render(<Sparkline values={[5]} width={60} height={20} />)
+    // A zero-length segment with a round linecap is a visible dot.
+    expect(container.querySelector('path')?.getAttribute('d')).toBe('M30,10 L30,10')
+    expect(container.querySelector('path')?.getAttribute('stroke-linecap')).toBe('round')
+  })
+
+  it('draws a flat series through the middle, not pinned to an edge', () => {
+    const { container } = render(<Sparkline values={[7, 7, 7]} width={60} height={20} />)
+    expect(container.querySelector('path')?.getAttribute('d')).toBe('M3.25,10 L30,10 L56.75,10')
+  })
+
+  it('draws an all-zero series the same way — flat, never NaN', () => {
+    const { container } = render(<Sparkline values={[0, 0]} width={60} height={20} />)
+    const d = container.querySelector('path')?.getAttribute('d') ?? ''
+    expect(d).toBe('M3.25,10 L56.75,10')
+    expect(d).not.toContain('NaN')
+  })
+
+  it('plots negative values on their real position', () => {
+    const { container } = render(<Sparkline values={[-1, 1]} width={60} height={20} />)
+    expect(container.querySelector('path')?.getAttribute('d')).toBe('M3.25,16.75 L56.75,3.25')
+  })
+
+  it('closes over a non-finite datum instead of inventing a dip at zero', () => {
+    const { container } = render(
+      <Sparkline values={[1, Number.NaN, 3]} width={60} height={20} />,
+    )
+    expect(container.querySelector('path')?.getAttribute('d')).toBe('M3.25,16.75 L56.75,3.25')
+  })
+
+  it('omits the dot when the emphasized datum is not plottable', () => {
+    const { container } = render(<Sparkline values={[1, 2, Number.NaN]} />)
+    expect(container.querySelector('circle')).toBeNull()
+  })
+
+  it('renders nothing but the reserved box when every datum is non-finite', () => {
+    const { container } = render(
+      <Sparkline values={[Number.NaN, Number.POSITIVE_INFINITY]} width={60} height={20} />,
+    )
+    expect(container.querySelector('svg')).toBeNull()
+    expect(plot(container)).toHaveStyle({ width: '60px', height: '20px' })
+  })
+})
+
+describe('Sparkline bar variant', () => {
+  it('reproduces AllocationSparkbar arithmetic exactly at its 36px height', () => {
+    // floor 8, headroom 4 → a bar spans 8..32, i.e. `8 + f * (36 - 12)`.
+    const { container } = render(
+      <Sparkline variant="bar" values={[10, 0, 5]} width={90} height={36} />,
+    )
+    expect(bars(container).map((b) => b.style.height)).toEqual(['32px', '4px', '20px'])
+  })
+
+  it('scales the floor with the box so it cannot swallow a 20px strip', () => {
+    const { container } = render(
+      <Sparkline variant="bar" values={[10, 5]} width={60} height={20} />,
+    )
+    const heights = bars(container).map((b) => px(b.style.height))
+    // floor 20*2/9, cap 20 - 20/9.
+    expect(heights[0]).toBeCloseTo(20 - 20 / 9, 6)
+    expect(heights[1]).toBeCloseTo((20 * 2) / 9 + 0.5 * (20 - 20 / 9 - (20 * 2) / 9), 6)
+    for (const height of heights) expect(height).toBeLessThanOrEqual(20 + EPS)
+  })
+
+  it('lays bars out on a band scale that fits the width', () => {
+    const { container } = render(
+      <Sparkline variant="bar" values={[1, 2, 3, 4]} width={60} height={20} />,
+    )
+    const laid = bars(container).map((b) => ({
+      left: px(b.style.left),
+      width: px(b.style.width),
+    }))
+    laid.forEach((bar, index) => {
+      expect(bar.left).toBeCloseTo(2.1 + index * 15, 6)
+    })
+    for (const bar of laid) {
+      expect(bar.width).toBeCloseTo(10.8, 6)
+      expect(bar.left + bar.width).toBeLessThanOrEqual(60 + EPS)
+    }
+  })
+
+  it('renders a zero as a short dashed stub — paused, not missing', () => {
+    const { container } = render(
+      <Sparkline variant="bar" values={[10, 0]} width={60} height={36} />,
+    )
+    const paused = bars(container)[1]
+    expect(paused?.style.height).toBe('4px')
+    expect(paused?.style.border).toContain('dashed')
+    expect(paused?.style.background).toBe('rgb(var(--text-muted) / 0.18)')
+  })
+
+  it('treats zero as a real measurement when asked to', () => {
+    const { container } = render(
+      <Sparkline variant="bar" values={[10, 0]} width={60} height={36} zeroAsPaused={false} />,
+    )
+    const zero = bars(container)[1]
+    expect(zero?.style.height).toBe('8px')
+    expect(zero?.style.border).toBe('')
+    expect(zero?.style.background).toBe('rgb(var(--accent))')
+  })
+
+  it('gives the emphasized bar full strength and tints the rest', () => {
+    const { container } = render(
+      <Sparkline variant="bar" values={[3, 2, 1]} width={60} height={36} />,
+    )
+    expect(bars(container).map((b) => b.style.opacity)).toEqual(['0.55', '0.55', '1'])
+  })
+
+  it('emphasizes a named bar, and clamps an out-of-range index', () => {
+    const { container, rerender } = render(
+      <Sparkline variant="bar" values={[3, 2, 1]} emphasisIndex={0} />,
+    )
+    expect(bars(container).map((b) => b.style.opacity)).toEqual(['1', '0.55', '0.55'])
+
+    rerender(<Sparkline variant="bar" values={[3, 2, 1]} emphasisIndex={-4} />)
+    expect(bars(container).map((b) => b.style.opacity)).toEqual(['1', '0.55', '0.55'])
+  })
+
+  it('renders a uniform strip when emphasis is off', () => {
+    const { container } = render(
+      <Sparkline variant="bar" values={[3, 2, 1]} emphasizeLast={false} />,
+    )
+    expect(bars(container).map((b) => b.style.opacity)).toEqual(['1', '1', '1'])
+  })
+
+  it('rounds bars lightly rather than into pills', () => {
+    const { container } = render(<Sparkline variant="bar" values={[1, 2]} />)
+    expect(bars(container)[0]?.style.borderRadius).toBe('calc(var(--radius-xs) / 2)')
+  })
+
+  it('draws an all-zero series at the floor, never at full height', () => {
+    const { container } = render(
+      <Sparkline
+        variant="bar"
+        values={[0, 0]}
+        width={60}
+        height={36}
+        zeroAsPaused={false}
+      />,
+    )
+    expect(bars(container).map((b) => b.style.height)).toEqual(['8px', '8px'])
+  })
+
+  it('clamps a negative value to the floor and absorbs a non-finite one', () => {
+    const { container } = render(
+      <Sparkline
+        variant="bar"
+        values={[10, -5, Number.NaN]}
+        width={90}
+        height={36}
+        zeroAsPaused={false}
+      />,
+    )
+    const heights = bars(container).map((b) => b.style.height)
+    expect(heights).toEqual(['32px', '8px', '8px'])
+    expect(heights.join()).not.toContain('NaN')
+  })
+
+  it('renders a single bar without dividing by zero', () => {
+    const { container } = render(
+      <Sparkline variant="bar" values={[42]} width={60} height={36} />,
+    )
+    expect(bars(container)).toHaveLength(1)
+    expect(bars(container)[0]?.style.height).toBe('32px')
+  })
+
+  it('renders nothing but the reserved box for an empty series', () => {
+    const { container } = render(
+      <Sparkline variant="bar" values={[]} width={60} height={20} />,
+    )
+    expect(bars(container)).toHaveLength(0)
+    expect(plot(container)).toHaveStyle({ width: '60px', height: '20px' })
+  })
+})
+
+describe('Sparkline accessibility', () => {
+  it('is an image with a name when it carries meaning', () => {
+    render(<Sparkline values={[1, 2, 3]} label="Impressions, last 12 weeks" />)
+    expect(
+      screen.getByRole('img', { name: 'Impressions, last 12 weeks' }),
+    ).toBeInTheDocument()
+  })
+
+  it('hides itself from assistive tech when unlabelled and decorative', () => {
+    const { container } = render(<Sparkline values={[1, 2, 3]} />)
+    expect(plot(container)).toHaveAttribute('aria-hidden', 'true')
+    expect(plot(container)).not.toHaveAttribute('role')
+  })
+
+  it('keeps the inner svg out of the accessibility tree either way', () => {
+    const { container } = render(<Sparkline values={[1, 2, 3]} label="Trend" />)
+    expect(container.querySelector('svg')).toHaveAttribute('aria-hidden', 'true')
+    expect(container.querySelector('svg')).toHaveAttribute('focusable', 'false')
+  })
+})

package/src/__tests__/stat-layer.test.tsx

@@ -0,0 +1,271 @@
+/**
+ * DeltaChip + StatCard — the ADR-146 D5 stat layer.
+ *
+ * These pin the four behaviours that the three delta forks and the ~26
+ * stat-tile forks got wrong or omitted, and that a well-meaning refactor
+ * would quietly undo:
+ *
+ *   1. `invert` flips the COLOUR, not the arrow. Cost metrics are half our
+ *      KPIs; "up is green" is wrong for every one of them.
+ *   2. Direction is carried by glyph + text, never by hue alone.
+ *   3. The tray is conditional — a bare stat card must not grow a frame.
+ *   4. `pending` renders a well, never a fabricated `0`, and suppresses the
+ *      delta along with it.
+ *
+ * The suite runs with `css: false`, so it asserts the values handed to the
+ * browser, not painted pixels. CSS validity is covered by the source scan in
+ * `token-shape.test.ts`.
+ */
+import { describe, expect, it } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { DeltaChip } from '../delta-chip'
+import { StatCard } from '../stat-card'
+
+/** The chip is the element carrying the tone background. */
+function chipOf(container: HTMLElement): HTMLElement {
+  const el = container.querySelector('span[style]')
+  if (!el) throw new Error('no chip rendered')
+  return el as HTMLElement
+}
+
+describe('DeltaChip', () => {
+  it('renders the magnitude, never a duplicated sign', () => {
+    render(<DeltaChip value={-12.5} />)
+    expect(screen.getByText('12.5%')).toBeInTheDocument()
+    expect(screen.queryByText('-12.5%')).not.toBeInTheDocument()
+  })
+
+  it('formats absolute values without a percent sign', () => {
+    render(<DeltaChip value={1204} format="absolute" />)
+    expect(screen.getByText('1,204')).toBeInTheDocument()
+  })
+
+  it('names its direction for assistive tech, not only in colour', () => {
+    const up = render(<DeltaChip value={4} />)
+    expect(up.container.textContent).toContain('Up')
+    up.unmount()
+
+    const down = render(<DeltaChip value={-4} />)
+    expect(down.container.textContent).toContain('Down')
+    down.unmount()
+
+    const flat = render(<DeltaChip value={0} />)
+    expect(flat.container.textContent).toContain('No change')
+  })
+
+  it('paints a rise as success and a fall as destructive', () => {
+    const up = render(<DeltaChip value={4} />)
+    expect(chipOf(up.container).style.background).toContain('--success-bg')
+    up.unmount()
+
+    const down = render(<DeltaChip value={-4} />)
+    expect(chipOf(down.container).style.background).toContain('--destructive-bg')
+  })
+
+  it('inverts the COLOUR for cost-shaped metrics, not the arrow', () => {
+    // A 4% rise in CPA is bad news painted red — but the arrow still
+    // points up, because the number still went up.
+    const worse = render(<DeltaChip value={4} invert />)
+    expect(chipOf(worse.container).style.background).toContain('--destructive-bg')
+    expect(worse.container.textContent).toContain('Up')
+    worse.unmount()
+
+    const better = render(<DeltaChip value={-4} invert />)
+    expect(chipOf(better.container).style.background).toContain('--success-bg')
+    expect(better.container.textContent).toContain('Down')
+  })
+
+  it('reads zero as neutral, in neither semantic colour', () => {
+    const { container } = render(<DeltaChip value={0} />)
+    const bg = chipOf(container).style.background
+    expect(bg).not.toContain('--success')
+    expect(bg).not.toContain('--destructive')
+  })
+
+  it('degrades a non-finite delta to flat rather than throwing', () => {
+    const { container } = render(<DeltaChip value={Number.NaN} />)
+    expect(container.textContent).toContain('No change')
+    // `format.ts` renders garbage as an em-dash — never as "NaN%".
+    expect(container.textContent).not.toContain('NaN')
+  })
+
+  it('reads a change that rounds away as flat, not as a green zero', () => {
+    // +0.04% printed at one decimal is "0.0%". Taking the arrow from the
+    // raw sign put a green UP arrow next to a zero — the chip contradicting
+    // its own numeral.
+    const { container } = render(<DeltaChip value={0.04} />)
+    expect(screen.getByText('0.0%')).toBeInTheDocument()
+    expect(container.textContent).toContain('No change')
+    const bg = chipOf(container).style.background
+    expect(bg).not.toContain('--success')
+    expect(bg).not.toContain('--destructive')
+  })
+
+  it('still reads a change that survives the precision', () => {
+    const { container } = render(<DeltaChip value={0.04} decimals={2} />)
+    expect(screen.getByText('0.04%')).toBeInTheDocument()
+    expect(container.textContent).toContain('Up')
+  })
+
+  it('honours an explicit direction override', () => {
+    // Rank 4 → 2 is an improvement expressed as a negative number.
+    const { container } = render(<DeltaChip value={-2} direction="up" format="absolute" />)
+    expect(container.textContent).toContain('Up')
+    expect(chipOf(container).style.background).toContain('--success-bg')
+  })
+
+  it('never puts a second alpha on the alpha-carrying tone fills', () => {
+    // `--success-bg` is declared `R G B / A`. A second alpha expands to
+    // `rgb(... / 0.12 / 0.5)`, which the browser silently discards.
+    const { container } = render(<DeltaChip value={4} />)
+    expect(chipOf(container).style.background).toBe('rgb(var(--success-bg))')
+  })
+})
+
+describe('DeltaChip sentiment (ADR-146 amendment, phase audit H1)', () => {
+  /**
+   * A falling number is not always a failure. The community leaderboard shows
+   * a contribution count on a NAMED PERSON, and painting a quieter month in
+   * `--destructive` spends the error channel on something that is not an
+   * error. `invert` cannot express this — it only flips WHICH direction is
+   * good, so a down-trend still reads as an outcome.
+   */
+  it('renders a fall in the neutral tone, not destructive, when sentiment is none', () => {
+    const { container: judged } = render(<DeltaChip value={-4} format="absolute" />)
+    const { container: unjudged } = render(
+      <DeltaChip value={-4} format="absolute" sentiment="none" />,
+    )
+    const styleOf = (c: HTMLElement) =>
+      (c.querySelector('[style]') as HTMLElement | null)?.getAttribute('style') ?? ''
+
+    expect(styleOf(judged)).toContain('--destructive')
+    expect(styleOf(unjudged)).not.toContain('--destructive')
+    expect(styleOf(unjudged)).toContain('--muted')
+  })
+
+  it('still reports the direction — only the colour declines to judge it', () => {
+    const { container } = render(
+      <DeltaChip value={-4} format="absolute" sentiment="none" />,
+    )
+    // The arrow is what carries direction, so identity is never colour-alone.
+    expect(container.querySelector('svg')).not.toBeNull()
+    expect(container.textContent).toContain('4')
+  })
+
+  it('leaves the default behaviour alone', () => {
+    const { container } = render(<DeltaChip value={-4} format="absolute" />)
+    expect(
+      (container.querySelector('[style]') as HTMLElement | null)?.getAttribute('style'),
+    ).toContain('--destructive')
+  })
+})
+
+describe('StatCard', () => {
+  it('renders label and value', () => {
+    render(<StatCard label="Sessions" value="12,480" />)
+    expect(screen.getByText('Sessions')).toBeInTheDocument()
+    expect(screen.getByText('12,480')).toBeInTheDocument()
+  })
+
+  it('has the delta slot the forked tiles all lacked', () => {
+    render(<StatCard label="Sessions" value="12,480" delta={{ value: 8.4 }} />)
+    expect(screen.getByText('8.4%')).toBeInTheDocument()
+  })
+
+  it('is a plain card with NO tray when there is nothing but the panel', () => {
+    const { container } = render(<StatCard label="Sessions" value="12,480" />)
+    expect(container.querySelector('.ds-card-tray')).toBeNull()
+    expect(container.querySelector('[data-framed]')).toBeNull()
+    expect(container.querySelector('.ds-card-surface')).not.toBeNull()
+  })
+
+  it('promotes to the framed tray once a footer exists', () => {
+    const { container } = render(
+      <StatCard label="Sessions" value="12,480" footer="vs. last 30 days" />,
+    )
+    expect(container.querySelector('.ds-card-tray')).not.toBeNull()
+    expect(container.querySelector('[data-framed="true"]')).not.toBeNull()
+    expect(screen.getByText('vs. last 30 days')).toBeInTheDocument()
+  })
+
+  it('promotes on a footer link alone, and keeps it keyboard-reachable', () => {
+    const { container } = render(
+      <StatCard
+        label="Sessions"
+        value="12,480"
+        footerLink={{ label: 'View report', onClick: () => {} }}
+      />,
+    )
+    expect(container.querySelector('.ds-card-tray')).not.toBeNull()
+    const link = screen.getByRole('button', { name: /View report/ })
+    expect(link.className).toContain('focus-visible:[box-shadow:var(--ring-focus)]')
+  })
+
+  it('renders a well instead of a fabricated zero when pending', () => {
+    render(
+      <StatCard
+        label="Conversion rate"
+        value="0%"
+        pending
+        pendingHint="No conversions tracked yet"
+        delta={{ value: 12 }}
+      />,
+    )
+    expect(screen.getByText('Not available')).toBeInTheDocument()
+    expect(screen.getByText('No conversions tracked yet')).toBeInTheDocument()
+    expect(screen.queryByText('0%')).not.toBeInTheDocument()
+    // A delta on data we do not have is a fabricated figure too.
+    expect(screen.queryByText('12.0%')).not.toBeInTheDocument()
+  })
+
+  it('renders the pending well into the SAME reserved slot as the value', () => {
+    // The well used to be padded like a control (8px) and stood 10px taller
+    // than the value row it replaces, so a pending card grew its whole grid
+    // row on load. Both branches now render into one --space-6 slot.
+    const loaded = render(<StatCard label="Sessions" value="12,480" />)
+    const loadedSlot = loaded.container.querySelector<HTMLElement>(
+      'div[style*="min-height"]',
+    )
+    expect(loadedSlot?.style.minHeight).toBe('var(--space-6)')
+    loaded.unmount()
+
+    const { container } = render(<StatCard label="Sessions" value="12,480" pending />)
+    const slot = container.querySelector<HTMLElement>('div[style*="min-height"]')
+    expect(slot?.style.minHeight).toBe('var(--space-6)')
+    expect(slot?.textContent).toContain('Not available')
+  })
+
+  it('sets the pending hint in a token that clears the text floor', () => {
+    // --text-muted is documented in tokens.css as non-text/disabled chrome
+    // (3.47:1 on a white card). The hint is prose a user has to read.
+    render(
+      <StatCard label="Sessions" value="0" pending pendingHint="No data yet" />,
+    )
+    const hint = screen.getByText('No data yet')
+    expect(hint.style.color).toBe('rgb(var(--text-tertiary))')
+  })
+
+  it('steps the icon tile off the card surface so it survives dark mode', () => {
+    // --surface-card ON --surface-card is the same colour in dark, leaving
+    // an 8%-alpha border as the tile's only edge.
+    const { container } = render(
+      <StatCard label="Sessions" value="12,480" icon={<span>i</span>} />,
+    )
+    const tile = container.querySelector<HTMLElement>('span[style*="--ctrl-md"]')
+    expect(tile?.style.background).toBe('rgb(var(--surface-raised))')
+  })
+
+  it('sets the value solid and reserves its width', () => {
+    render(<StatCard label="Sessions" value="12,480" size="lg" />)
+    const value = screen.getByText('12,480')
+    expect(value.className).toContain('leading-none')
+    expect(value.className).toContain('tabular-nums')
+    expect(value.className).toContain('text-[24px]')
+    expect(value.style.minWidth).toBe('6ch')
+  })
+
+  it('uses the 18px value at md', () => {
+    render(<StatCard label="Sessions" value="12,480" />)
+    expect(screen.getByText('12,480').className).toContain('text-[18px]')
+  })
+})