@startsimpli/ui 0.4.89 → 0.4.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.89",
+  "version": "0.4.90",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -43,8 +43,8 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "^0.5.54",
-    "@startsimpli/auth": "^0.4.34"
+    "@startsimpli/auth": "^0.4.34",
+    "@startsimpli/api": "^0.5.54"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/components/dashboard/AreaTrend.tsx

@@ -0,0 +1,182 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+export interface AreaTrendProps {
+  /** The series, oldest first. Empty / single-point / flat series all render. */
+  data: number[]
+  /** Any CSS colour. Defaults to `currentColor` so the caller tints via `text-*`. */
+  color?: string
+  /** Plot height in px (excludes the optional header row). */
+  height?: number
+  /** Optional header row, left side. */
+  label?: string
+  /** Optional header row, right side. */
+  value?: React.ReactNode
+  /** Draw faint horizontal baselines behind the plot. */
+  showBaseline?: boolean
+  /** How many baselines when `showBaseline` — clamped to 1..10. */
+  baselineCount?: number
+  /** Overrides the generated description. */
+  ariaLabel?: string
+  className?: string
+}
+
+/** Internal viewBox width; `preserveAspectRatio="none"` stretches it to the box. */
+const VIEW_W = 100
+
+/**
+ * Deterministic id from a seed so the gradient survives SSR without `useId`
+ * (which would force this into a client component). Two AreaTrends sharing a
+ * colour share a gradient def — same stops, so the collision is harmless.
+ */
+function gradientIdFor(seed: string): string {
+  let hash = 0
+  for (let i = 0; i < seed.length; i += 1) {
+    hash = (hash * 31 + seed.charCodeAt(i)) | 0
+  }
+  return `area-trend-${(hash >>> 0).toString(36)}`
+}
+
+interface Geometry {
+  line: string
+  area: string
+}
+
+/**
+ * Maps a series onto the viewBox. A flat series (max === min, including a
+ * single point and an all-zero series) rides the vertical centre rather than
+ * dividing by a zero range.
+ */
+export function areaTrendGeometry(data: number[], height: number): Geometry | null {
+  const points = data.filter((n) => Number.isFinite(n))
+  if (points.length === 0) return null
+
+  const padding = 2
+  const usable = Math.max(height - padding * 2, 1)
+  const min = Math.min(...points)
+  const max = Math.max(...points)
+  const flat = max === min
+
+  const coords = points.map((v, i) => {
+    const x = points.length === 1 ? VIEW_W / 2 : (i / (points.length - 1)) * VIEW_W
+    const y = flat ? height / 2 : height - padding - ((v - min) / (max - min)) * usable
+    return { x, y }
+  })
+
+  // A single point has no segment to stroke — draw a flat rule across the box
+  // so the caller still sees the value's level instead of an empty frame.
+  const path =
+    coords.length === 1
+      ? `M 0,${coords[0].y} L ${VIEW_W},${coords[0].y}`
+      : `M ${coords.map((p) => `${p.x},${p.y}`).join(' L ')}`
+
+  return {
+    line: path,
+    area: `${path} L ${VIEW_W},${height} L 0,${height} Z`,
+  }
+}
+
+function describe(data: number[], label?: string): string {
+  const points = data.filter((n) => Number.isFinite(n))
+  const subject = label ? `${label} trend` : 'Trend'
+  if (points.length === 0) return `${subject}: no data`
+  if (points.length === 1) return `${subject}: single value ${points[0]}`
+
+  const first = points[0]
+  const last = points[points.length - 1]
+  const shape = last > first ? 'rising' : last < first ? 'falling' : 'flat'
+  return `${subject}: ${shape} over ${points.length} points, from ${first} to ${last}`
+}
+
+/**
+ * A gradient-filled area chart over a plain number series. Pure SVG — no
+ * charting dependency, no hooks, safe to render on the server.
+ */
+export function AreaTrend({
+  data,
+  color = 'currentColor',
+  height = 96,
+  label,
+  value,
+  showBaseline = false,
+  baselineCount = 3,
+  ariaLabel,
+  className,
+}: AreaTrendProps) {
+  const safeHeight = Math.max(height, 1)
+  const geometry = areaTrendGeometry(data, safeHeight)
+  const gradientId = gradientIdFor(`${color}|${safeHeight}`)
+  const lines = Math.min(Math.max(Math.round(baselineCount), 1), 10)
+  const hasHeader = label !== undefined || value !== undefined
+
+  return (
+    <div className={cn('w-full', className)}>
+      {hasHeader && (
+        <div className="mb-2 flex items-baseline justify-between gap-2">
+          {label !== undefined && (
+            <span className="truncate text-xs font-medium uppercase tracking-wide text-muted-foreground">
+              {label}
+            </span>
+          )}
+          {value !== undefined && (
+            <span className="shrink-0 text-sm font-semibold tabular-nums text-foreground">
+              {value}
+            </span>
+          )}
+        </div>
+      )}
+      <svg
+        width="100%"
+        height={safeHeight}
+        viewBox={`0 0 ${VIEW_W} ${safeHeight}`}
+        preserveAspectRatio="none"
+        role="img"
+        aria-label={ariaLabel ?? describe(data, label)}
+        className="block w-full overflow-visible"
+      >
+        <defs>
+          <linearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
+            <stop offset="0%" stopColor={color} stopOpacity={0.35} />
+            <stop offset="100%" stopColor={color} stopOpacity={0} />
+          </linearGradient>
+        </defs>
+
+        {showBaseline && (
+          <g className="text-border" aria-hidden="true">
+            {Array.from({ length: lines }, (_, i) => {
+              const y = ((i + 1) / (lines + 1)) * safeHeight
+              return (
+                <line
+                  key={i}
+                  x1={0}
+                  y1={y}
+                  x2={VIEW_W}
+                  y2={y}
+                  stroke="currentColor"
+                  strokeWidth={1}
+                  strokeDasharray="2 3"
+                  vectorEffect="non-scaling-stroke"
+                />
+              )
+            })}
+          </g>
+        )}
+
+        {geometry && (
+          <>
+            <path d={geometry.area} fill={`url(#${gradientId})`} stroke="none" />
+            <path
+              d={geometry.line}
+              fill="none"
+              stroke={color}
+              strokeWidth={2}
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              vectorEffect="non-scaling-stroke"
+            />
+          </>
+        )}
+      </svg>
+    </div>
+  )
+}

package/src/components/dashboard/DeltaPill.tsx

@@ -0,0 +1,119 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+export type DeltaDirection = 'up' | 'down' | 'neutral'
+
+export interface DeltaPillProps {
+  /** The change itself. A number is signed + suffixed for you; a string is rendered verbatim. */
+  value: number | string
+  /** Overrides the direction inferred from a numeric `value`. Required to colour a string value. */
+  direction?: DeltaDirection
+  /** Appended to a numeric value — '%' by default. Ignored for string values. */
+  suffix?: string
+  /** Trailing context, e.g. 'vs last month'. */
+  label?: string
+  /** Prefix positive numbers with '+'. Defaults to true. */
+  showSign?: boolean
+  size?: 'sm' | 'md'
+  className?: string
+}
+
+/**
+ * Direction of a delta. Explicit `direction` always wins; otherwise a finite
+ * number is read by sign and everything else (strings, NaN, Infinity) is
+ * neutral — a pill can't claim a direction it can't derive.
+ */
+export function resolveDeltaDirection(
+  value: number | string,
+  direction?: DeltaDirection,
+): DeltaDirection {
+  if (direction) return direction
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    if (value > 0) return 'up'
+    if (value < 0) return 'down'
+  }
+  return 'neutral'
+}
+
+/** Em dash for a number that can't be shown (NaN / ±Infinity). */
+export const DELTA_UNAVAILABLE = '—'
+
+function formatDelta(
+  value: number | string,
+  suffix: string,
+  showSign: boolean,
+): string {
+  if (typeof value === 'string') return value
+  if (!Number.isFinite(value)) return DELTA_UNAVAILABLE
+  const sign = showSign && value > 0 ? '+' : ''
+  return `${sign}${value}${suffix}`
+}
+
+const DIRECTION_TEXT: Record<DeltaDirection, string> = {
+  up: 'text-success',
+  down: 'text-destructive',
+  neutral: 'text-secondary-foreground',
+}
+
+/** Screen-reader wording so direction never rests on colour alone. */
+const DIRECTION_WORD: Record<DeltaDirection, string> = {
+  up: 'up',
+  down: 'down',
+  neutral: 'unchanged',
+}
+
+function DirectionArrow({ direction }: { direction: DeltaDirection }) {
+  const d =
+    direction === 'up'
+      ? 'M12 19V5M5 12l7-7 7 7'
+      : direction === 'down'
+        ? 'M12 5v14M5 12l7 7 7-7'
+        : 'M5 12h14'
+
+  return (
+    <svg
+      className="h-3 w-3 shrink-0"
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+      strokeWidth={2.5}
+      aria-hidden="true"
+    >
+      <path strokeLinecap="round" strokeLinejoin="round" d={d} />
+    </svg>
+  )
+}
+
+/**
+ * A rounded chip carrying a signed change and its direction — "+12% vs last
+ * month". Used standalone or as the `delta` of a {@link StatTile}.
+ */
+export function DeltaPill({
+  value,
+  direction,
+  suffix = '%',
+  label,
+  showSign = true,
+  size = 'md',
+  className,
+}: DeltaPillProps) {
+  const resolved = resolveDeltaDirection(value, direction)
+  const text = formatDelta(value, suffix, showSign)
+
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center gap-1 rounded-full bg-secondary font-medium',
+        size === 'sm' ? 'px-2 py-0.5 text-xs' : 'px-2.5 py-1 text-sm',
+        DIRECTION_TEXT[resolved],
+        className,
+      )}
+      data-direction={resolved}
+    >
+      <DirectionArrow direction={resolved} />
+      <span className="sr-only">{DIRECTION_WORD[resolved]}</span>
+      <span className="tabular-nums">{text}</span>
+      {label ? <span className="opacity-80">{label}</span> : null}
+    </span>
+  )
+}

package/src/components/dashboard/DonutChart.tsx

@@ -0,0 +1,189 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+
+export interface DonutSegment {
+  label: string
+  value: number
+  /** Any CSS colour. Brand palettes are the caller's business; defaults to `currentColor`. */
+  color?: string
+}
+
+export interface DonutChartProps {
+  segments: DonutSegment[]
+  /** Big number in the hole. */
+  centerValue?: React.ReactNode
+  /** Muted caption under `centerValue`. */
+  centerLabel?: string
+  /** Outer diameter in px. */
+  size?: number
+  /** Ring width in px — clamped so the ring always fits inside `size`. */
+  thickness?: number
+  /** Render the label/value list beside the ring. */
+  showLegend?: boolean
+  /** Formats the right-hand column of a legend row. Defaults to the raw value. */
+  formatLegendValue?: (segment: DonutSegment) => React.ReactNode
+  /** Overrides the generated description. */
+  ariaLabel?: string
+  className?: string
+}
+
+export interface DonutSlice extends DonutSegment {
+  /** 0..1 share of the total. */
+  fraction: number
+  /** 0..1 share consumed by the preceding slices. */
+  offset: number
+}
+
+/**
+ * Turns raw segments into ring slices. Negative values are clamped to zero
+ * (a ring cannot show a negative arc) and a total of zero yields no slices, so
+ * an all-zero or empty input renders the bare track instead of NaN arcs.
+ */
+export function donutSlices(segments: DonutSegment[]): {
+  slices: DonutSlice[]
+  total: number
+} {
+  const cleaned = segments.map((s) => ({
+    ...s,
+    value: Number.isFinite(s.value) ? Math.max(s.value, 0) : 0,
+  }))
+  const total = cleaned.reduce((sum, s) => sum + s.value, 0)
+  if (total <= 0) return { slices: [], total: 0 }
+
+  let offset = 0
+  const slices = cleaned.map((s) => {
+    const fraction = s.value / total
+    const slice: DonutSlice = { ...s, fraction, offset }
+    offset += fraction
+    return slice
+  })
+  return { slices, total }
+}
+
+function describe(slices: DonutSlice[], centerLabel?: string): string {
+  const subject = centerLabel ? `${centerLabel} breakdown` : 'Breakdown'
+  if (slices.length === 0) return `${subject}: no data`
+  const parts = slices.map(
+    (s) => `${s.label} ${Math.round(s.fraction * 1000) / 10}%`,
+  )
+  return `${subject}: ${parts.join(', ')}`
+}
+
+/**
+ * A proportional ring with a total in the middle. Pure SVG `stroke-dasharray` —
+ * no charting dependency, no hooks, safe to render on the server.
+ */
+export function DonutChart({
+  segments,
+  centerValue,
+  centerLabel,
+  size = 180,
+  thickness = 18,
+  showLegend = false,
+  formatLegendValue,
+  ariaLabel,
+  className,
+}: DonutChartProps) {
+  const safeSize = Math.max(size, 8)
+  // Keep the stroke inside the viewBox no matter what the caller asks for.
+  const safeThickness = Math.min(Math.max(thickness, 1), safeSize / 2)
+  const radius = Math.max((safeSize - safeThickness) / 2, 0.5)
+  const circumference = 2 * Math.PI * radius
+  const center = safeSize / 2
+
+  const { slices } = donutSlices(segments)
+  const hasCenter = centerValue !== undefined || centerLabel !== undefined
+
+  return (
+    <div
+      className={cn(
+        'flex items-center gap-6',
+        showLegend ? 'flex-row flex-wrap' : 'flex-col',
+        className,
+      )}
+    >
+      <div
+        className="relative shrink-0"
+        style={{ width: safeSize, height: safeSize }}
+      >
+        <svg
+          width={safeSize}
+          height={safeSize}
+          viewBox={`0 0 ${safeSize} ${safeSize}`}
+          role="img"
+          aria-label={ariaLabel ?? describe(slices, centerLabel)}
+          className="block -rotate-90"
+        >
+          {/* Track — also the entire chart when there is nothing to plot. */}
+          <circle
+            cx={center}
+            cy={center}
+            r={radius}
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={safeThickness}
+            className="text-border"
+          />
+          {slices.map((slice, i) => {
+            const dash = slice.fraction * circumference
+            return (
+              <circle
+                key={`${slice.label}-${i}`}
+                cx={center}
+                cy={center}
+                r={radius}
+                fill="none"
+                stroke={slice.color ?? 'currentColor'}
+                strokeWidth={safeThickness}
+                // A lone 100% slice gets a zero-length gap, which draws the
+                // full ring rather than a hairline.
+                strokeDasharray={`${dash} ${Math.max(circumference - dash, 0)}`}
+                strokeDashoffset={-slice.offset * circumference}
+              />
+            )
+          })}
+        </svg>
+
+        {hasCenter && (
+          <div className="pointer-events-none absolute inset-0 flex flex-col items-center justify-center px-3 text-center">
+            {centerValue !== undefined && (
+              <span className="text-xl font-semibold tabular-nums tracking-tight text-foreground">
+                {centerValue}
+              </span>
+            )}
+            {centerLabel !== undefined && (
+              <span className="mt-0.5 text-xs text-muted-foreground">
+                {centerLabel}
+              </span>
+            )}
+          </div>
+        )}
+      </div>
+
+      {showLegend && segments.length > 0 && (
+        <ul className="min-w-0 flex-1 space-y-2">
+          {segments.map((segment, i) => (
+            <li
+              key={`${segment.label}-${i}`}
+              className="flex items-center justify-between gap-3 text-sm"
+            >
+              <span className="flex min-w-0 items-center gap-2">
+                <span
+                  className="h-2.5 w-2.5 shrink-0 rounded-full"
+                  style={{ backgroundColor: segment.color ?? 'currentColor' }}
+                  aria-hidden="true"
+                />
+                <span className="truncate text-muted-foreground">
+                  {segment.label}
+                </span>
+              </span>
+              <span className="shrink-0 font-medium tabular-nums text-foreground">
+                {formatLegendValue ? formatLegendValue(segment) : segment.value}
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}

package/src/components/dashboard/StatTile.tsx

@@ -0,0 +1,98 @@
+import * as React from 'react'
+import { cn } from '../../lib/utils'
+import { AreaTrend } from './AreaTrend'
+import { DeltaPill, type DeltaPillProps } from './DeltaPill'
+
+export type StatTileSize = 'sm' | 'md' | 'lg' | 'xl'
+
+export interface StatTileProps {
+  /** Small uppercase kicker above the numeral. */
+  label: string
+  /** The headline figure. Pre-format it (currency, compaction) — the tile only styles it. */
+  value: React.ReactNode
+  /** Muted line under the value, e.g. 'Streams · last 28 days'. */
+  caption?: string
+  /** Change chip under the caption. */
+  delta?: DeltaPillProps
+  /** Inline trend drawn to the right of the numeral. */
+  sparkline?: number[]
+  /** Any CSS colour for the sparkline; defaults to the tile's `text-primary` tint. */
+  sparklineColor?: string
+  /** Numeral scale — `lg` (text-4xl) by default, `xl` for a hero figure. */
+  size?: StatTileSize
+  /** Extra content below the delta. */
+  children?: React.ReactNode
+  className?: string
+}
+
+const VALUE_SIZE: Record<StatTileSize, string> = {
+  sm: 'text-2xl',
+  md: 'text-3xl',
+  lg: 'text-4xl',
+  xl: 'text-5xl',
+}
+
+/**
+ * A card built around one big display numeral: kicker, figure, optional
+ * caption, optional delta chip, optional inline sparkline. Presentational and
+ * hook-free — safe to render on the server.
+ */
+export function StatTile({
+  label,
+  value,
+  caption,
+  delta,
+  sparkline,
+  sparklineColor,
+  size = 'lg',
+  children,
+  className,
+}: StatTileProps) {
+  const hasSparkline = Array.isArray(sparkline) && sparkline.length > 0
+
+  return (
+    <div
+      className={cn(
+        'rounded-xl border border-border bg-card p-5 text-card-foreground shadow-sm',
+        className,
+      )}
+    >
+      <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+        {label}
+      </p>
+
+      <div className="mt-2 flex items-center justify-between gap-4">
+        <p
+          className={cn(
+            'min-w-0 font-semibold tabular-nums tracking-tight text-foreground',
+            VALUE_SIZE[size],
+          )}
+        >
+          {value}
+        </p>
+
+        {hasSparkline && (
+          <AreaTrend
+            data={sparkline}
+            color={sparklineColor}
+            height={44}
+            ariaLabel={`${label} trend`}
+            className="w-24 shrink-0 text-primary sm:w-32"
+          />
+        )}
+      </div>
+
+      {caption && (
+        <p className="mt-1 text-sm text-muted-foreground">{caption}</p>
+      )}
+
+      {delta && (
+        <div className="mt-3">
+          <DeltaPill size="sm" {...delta} />
+        </div>
+      )}
+
+      {children}
+    </div>
+  )
+}

package/src/components/dashboard/__tests__/display-primitives.test.tsx

@@ -0,0 +1,452 @@
+import { render, screen } from '@testing-library/react'
+import { AreaTrend, areaTrendGeometry } from '../AreaTrend'
+import { DeltaPill, resolveDeltaDirection, DELTA_UNAVAILABLE } from '../DeltaPill'
+import { DonutChart, donutSlices } from '../DonutChart'
+import { StatTile } from '../StatTile'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Every path `d` in the rendered SVG — the thing that goes NaN when maths breaks. */
+function pathData(container: HTMLElement): string[] {
+  return Array.from(container.querySelectorAll('path')).map(
+    (p) => p.getAttribute('d') ?? '',
+  )
+}
+
+function circleAttrs(container: HTMLElement, attr: string): string[] {
+  return Array.from(container.querySelectorAll('circle')).map(
+    (c) => c.getAttribute(attr) ?? '',
+  )
+}
+
+function expectNoNaN(values: string[]) {
+  values.forEach((v) => expect(v).not.toMatch(/NaN|Infinity/))
+}
+
+// ---------------------------------------------------------------------------
+// DeltaPill
+// ---------------------------------------------------------------------------
+
+describe('resolveDeltaDirection', () => {
+  it('reads direction from the sign of a finite number', () => {
+    expect(resolveDeltaDirection(12)).toBe('up')
+    expect(resolveDeltaDirection(-3.5)).toBe('down')
+  })
+
+  it('treats zero as neutral', () => {
+    expect(resolveDeltaDirection(0)).toBe('neutral')
+    expect(resolveDeltaDirection(-0)).toBe('neutral')
+  })
+
+  it('treats a non-finite number as neutral rather than guessing', () => {
+    expect(resolveDeltaDirection(NaN)).toBe('neutral')
+    expect(resolveDeltaDirection(Infinity)).toBe('neutral')
+    expect(resolveDeltaDirection(-Infinity)).toBe('neutral')
+  })
+
+  it('treats a string as neutral unless direction is given', () => {
+    expect(resolveDeltaDirection('+12%')).toBe('neutral')
+    expect(resolveDeltaDirection('+12%', 'up')).toBe('up')
+  })
+
+  it('lets an explicit direction override the sign', () => {
+    expect(resolveDeltaDirection(-4, 'up')).toBe('up')
+  })
+})
+
+describe('DeltaPill', () => {
+  it('signs and suffixes a positive number', () => {
+    render(<DeltaPill value={12} />)
+    expect(screen.getByText('+12%')).toBeInTheDocument()
+  })
+
+  it('does not double-sign a negative number', () => {
+    render(<DeltaPill value={-3} />)
+    expect(screen.getByText('-3%')).toBeInTheDocument()
+  })
+
+  it('omits the sign when showSign is false', () => {
+    render(<DeltaPill value={12} showSign={false} />)
+    expect(screen.getByText('12%')).toBeInTheDocument()
+  })
+
+  it('renders a string value verbatim', () => {
+    render(<DeltaPill value="2.4x" />)
+    expect(screen.getByText('2.4x')).toBeInTheDocument()
+  })
+
+  it('shows a dash instead of NaN', () => {
+    render(<DeltaPill value={NaN} />)
+    expect(screen.getByText(DELTA_UNAVAILABLE)).toBeInTheDocument()
+  })
+
+  it('colours up as success and down as destructive', () => {
+    const { container: up } = render(<DeltaPill value={5} />)
+    expect(up.firstChild).toHaveClass('text-success')
+
+    const { container: down } = render(<DeltaPill value={-5} />)
+    expect(down.firstChild).toHaveClass('text-destructive')
+  })
+
+  it('falls back to a neutral tone at zero', () => {
+    const { container } = render(<DeltaPill value={0} />)
+    expect(container.firstChild).toHaveClass('text-secondary-foreground')
+    expect(container.firstChild).toHaveAttribute('data-direction', 'neutral')
+  })
+
+  it('names the direction for screen readers, not just in colour', () => {
+    render(<DeltaPill value={12} label="vs last month" />)
+    expect(screen.getByText('up')).toHaveClass('sr-only')
+    expect(screen.getByText('vs last month')).toBeInTheDocument()
+  })
+
+  it('sits on the secondary surface so it reads on light and dark', () => {
+    const { container } = render(<DeltaPill value={1} />)
+    expect(container.firstChild).toHaveClass('bg-secondary')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// StatTile
+// ---------------------------------------------------------------------------
+
+describe('StatTile', () => {
+  it('renders the label, value and caption', () => {
+    render(
+      <StatTile
+        label="Estimated this month"
+        value="$48,500"
+        caption="Streams · last 28 days"
+      />,
+    )
+    expect(screen.getByText('Estimated this month')).toBeInTheDocument()
+    expect(screen.getByText('$48,500')).toBeInTheDocument()
+    expect(screen.getByText('Streams · last 28 days')).toBeInTheDocument()
+  })
+
+  it('defaults to the large numeral and honours an explicit size', () => {
+    const { container: def } = render(<StatTile label="A" value="1" />)
+    expect(def.querySelector('p.text-4xl')).toBeInTheDocument()
+
+    const { container: xl } = render(<StatTile label="A" value="1" size="xl" />)
+    expect(xl.querySelector('p.text-5xl')).toBeInTheDocument()
+  })
+
+  it('renders a delta pill when given one', () => {
+    render(
+      <StatTile
+        label="Earnings"
+        value="$48,500"
+        delta={{ value: 12, label: 'vs last month' }}
+      />,
+    )
+    expect(screen.getByText('+12%')).toBeInTheDocument()
+    expect(screen.getByText('vs last month')).toBeInTheDocument()
+  })
+
+  it('renders an inline sparkline with a meaningful label', () => {
+    render(<StatTile label="Streams" value="18.4M" sparkline={[1, 4, 2, 8]} />)
+    expect(screen.getByRole('img', { name: /Streams trend/ })).toBeInTheDocument()
+  })
+
+  it('omits the sparkline for an empty series', () => {
+    render(<StatTile label="Streams" value="18.4M" sparkline={[]} />)
+    expect(screen.queryByRole('img')).not.toBeInTheDocument()
+  })
+
+  it('styles against theme tokens, not a fixed grey', () => {
+    const { container } = render(<StatTile label="A" value="1" />)
+    expect(container.firstChild).toHaveClass('bg-card')
+    expect(container.firstChild).toHaveClass('border-border')
+    expect(screen.getByText('A')).toHaveClass('text-muted-foreground')
+    expect(screen.getByText('1')).toHaveClass('text-foreground')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// AreaTrend
+// ---------------------------------------------------------------------------
+
+describe('areaTrendGeometry', () => {
+  it('returns null for an empty series', () => {
+    expect(areaTrendGeometry([], 100)).toBeNull()
+  })
+
+  it('centres a flat series instead of dividing by a zero range', () => {
+    const geo = areaTrendGeometry([5, 5, 5], 100)
+    expect(geo).not.toBeNull()
+    expect(geo!.line).toBe('M 0,50 L 50,50 L 100,50')
+  })
+
+  it('centres an all-zero series the same way', () => {
+    const geo = areaTrendGeometry([0, 0, 0, 0], 80)
+    expectNoNaN([geo!.line])
+    expect(geo!.line).toBe('M 0,40 L 33.33333333333333,40 L 66.66666666666666,40 L 100,40')
+  })
+
+  it('draws a single point as a level rule across the box', () => {
+    const geo = areaTrendGeometry([7], 100)
+    expect(geo!.line).toBe('M 0,50 L 100,50')
+  })
+
+  it('normalises a series that crosses zero', () => {
+    const geo = areaTrendGeometry([-10, 0, 10], 100)
+    expectNoNaN([geo!.line, geo!.area])
+    // Lowest value sits at the bottom, highest at the top.
+    expect(geo!.line).toBe('M 0,98 L 50,50 L 100,2')
+  })
+
+  it('ignores non-finite points rather than emitting NaN', () => {
+    const geo = areaTrendGeometry([1, NaN, 3], 100)
+    expectNoNaN([geo!.line, geo!.area])
+  })
+})
+
+describe('AreaTrend', () => {
+  it('exposes an accessible description of the shape', () => {
+    render(<AreaTrend data={[1, 2, 3]} label="Spotify" />)
+    expect(
+      screen.getByRole('img', { name: /Spotify trend: rising over 3 points, from 1 to 3/ }),
+    ).toBeInTheDocument()
+  })
+
+  it('describes a falling series', () => {
+    render(<AreaTrend data={[9, 4, 1]} />)
+    expect(screen.getByRole('img', { name: /falling/ })).toBeInTheDocument()
+  })
+
+  it('renders an empty frame for no data without crashing', () => {
+    const { container } = render(<AreaTrend data={[]} />)
+    expect(screen.getByRole('img', { name: /no data/ })).toBeInTheDocument()
+    expect(pathData(container)).toEqual([])
+  })
+
+  it('never emits NaN coordinates for degenerate input', () => {
+    const cases: number[][] = [[], [0], [0, 0, 0], [4, 4], [-5, -5], [-2, 7, -9]]
+    cases.forEach((data) => {
+      const { container } = render(<AreaTrend data={data} />)
+      expectNoNaN(pathData(container))
+    })
+  })
+
+  it('tints from currentColor by default so the caller controls the colour', () => {
+    const { container } = render(<AreaTrend data={[1, 2]} />)
+    const line = container.querySelectorAll('path')[1]
+    expect(line).toHaveAttribute('stroke', 'currentColor')
+    expect(container.querySelector('stop')).toHaveAttribute(
+      'stop-color',
+      'currentColor',
+    )
+  })
+
+  it('accepts an explicit colour for both the line and the gradient', () => {
+    const { container } = render(<AreaTrend data={[1, 2]} color="#22C55E" />)
+    expect(container.querySelectorAll('path')[1]).toHaveAttribute('stroke', '#22C55E')
+    Array.from(container.querySelectorAll('stop')).forEach((stop) =>
+      expect(stop).toHaveAttribute('stop-color', '#22C55E'),
+    )
+  })
+
+  it('fades the fill from 35% to transparent', () => {
+    const { container } = render(<AreaTrend data={[1, 2]} />)
+    const stops = container.querySelectorAll('stop')
+    expect(stops[0]).toHaveAttribute('stop-opacity', '0.35')
+    expect(stops[1]).toHaveAttribute('stop-opacity', '0')
+  })
+
+  it('generates the same gradient id on every render so SSR matches the client', () => {
+    const { container: a } = render(<AreaTrend data={[1, 2]} color="#22C55E" />)
+    const { container: b } = render(<AreaTrend data={[9, 4]} color="#22C55E" />)
+    expect(a.querySelector('linearGradient')!.id).toBe(
+      b.querySelector('linearGradient')!.id,
+    )
+  })
+
+  it('draws baselines only when asked, and clamps the count', () => {
+    const { container: off } = render(<AreaTrend data={[1, 2]} />)
+    expect(off.querySelectorAll('line')).toHaveLength(0)
+
+    const { container: on } = render(<AreaTrend data={[1, 2]} showBaseline />)
+    expect(on.querySelectorAll('line')).toHaveLength(3)
+
+    const { container: clamped } = render(
+      <AreaTrend data={[1, 2]} showBaseline baselineCount={0} />,
+    )
+    expect(clamped.querySelectorAll('line')).toHaveLength(1)
+  })
+
+  it('renders the optional header row', () => {
+    render(<AreaTrend data={[1, 2]} label="Apple Music" value="4.1M" />)
+    expect(screen.getByText('Apple Music')).toBeInTheDocument()
+    expect(screen.getByText('4.1M')).toBeInTheDocument()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// DonutChart
+// ---------------------------------------------------------------------------
+
+describe('donutSlices', () => {
+  it('splits values into proportional fractions with running offsets', () => {
+    const { slices, total } = donutSlices([
+      { label: 'a', value: 3 },
+      { label: 'b', value: 1 },
+    ])
+    expect(total).toBe(4)
+    expect(slices.map((s) => s.fraction)).toEqual([0.75, 0.25])
+    expect(slices.map((s) => s.offset)).toEqual([0, 0.75])
+  })
+
+  it('gives a lone segment the whole ring', () => {
+    const { slices } = donutSlices([{ label: 'only', value: 42 }])
+    expect(slices).toHaveLength(1)
+    expect(slices[0].fraction).toBe(1)
+    expect(slices[0].offset).toBe(0)
+  })
+
+  it('returns no slices for an empty input', () => {
+    expect(donutSlices([])).toEqual({ slices: [], total: 0 })
+  })
+
+  it('returns no slices when every value is zero', () => {
+    expect(
+      donutSlices([
+        { label: 'a', value: 0 },
+        { label: 'b', value: 0 },
+      ]).slices,
+    ).toEqual([])
+  })
+
+  it('clamps negative values to zero instead of inverting the ring', () => {
+    const { slices, total } = donutSlices([
+      { label: 'a', value: -5 },
+      { label: 'b', value: 5 },
+    ])
+    expect(total).toBe(5)
+    expect(slices.map((s) => s.fraction)).toEqual([0, 1])
+  })
+
+  it('treats an all-negative input as empty', () => {
+    expect(
+      donutSlices([
+        { label: 'a', value: -1 },
+        { label: 'b', value: -2 },
+      ]).slices,
+    ).toEqual([])
+  })
+
+  it('ignores non-finite values', () => {
+    const { total } = donutSlices([
+      { label: 'a', value: NaN },
+      { label: 'b', value: 2 },
+    ])
+    expect(total).toBe(2)
+  })
+})
+
+describe('DonutChart', () => {
+  const segments = [
+    { label: 'Streaming', value: 22400, color: '#22B8F0' },
+    { label: 'Video', value: 6800, color: '#22C55E' },
+  ]
+
+  it('renders the centre value and caption', () => {
+    render(
+      <DonutChart
+        segments={segments}
+        centerValue="$29,200"
+        centerLabel="Revenue"
+      />,
+    )
+    expect(screen.getByText('$29,200')).toBeInTheDocument()
+    expect(screen.getByText('Revenue')).toBeInTheDocument()
+  })
+
+  it('describes the split for screen readers', () => {
+    render(<DonutChart segments={segments} centerLabel="Revenue" />)
+    expect(
+      screen.getByRole('img', {
+        name: /Revenue breakdown: Streaming 76.7%, Video 23.3%/,
+      }),
+    ).toBeInTheDocument()
+  })
+
+  it('draws one arc per segment plus the track', () => {
+    const { container } = render(<DonutChart segments={segments} />)
+    expect(container.querySelectorAll('circle')).toHaveLength(3)
+  })
+
+  it('draws a full ring with a zero-length gap for one 100% segment', () => {
+    const { container } = render(
+      <DonutChart segments={[{ label: 'All', value: 10 }]} size={100} thickness={10} />,
+    )
+    const circumference = 2 * Math.PI * 45
+    const dashes = circleAttrs(container, 'stroke-dasharray').filter(Boolean)
+    expect(dashes).toHaveLength(1)
+    expect(dashes[0]).toBe(`${circumference} 0`)
+  })
+
+  it('renders only the track for an empty or all-zero input', () => {
+    const { container: empty } = render(<DonutChart segments={[]} />)
+    expect(empty.querySelectorAll('circle')).toHaveLength(1)
+    expect(screen.getByRole('img', { name: /no data/ })).toBeInTheDocument()
+
+    const { container: zeros } = render(
+      <DonutChart segments={[{ label: 'a', value: 0 }]} />,
+    )
+    expect(zeros.querySelectorAll('circle')).toHaveLength(1)
+  })
+
+  it('never emits NaN geometry for degenerate input', () => {
+    const cases = [
+      [],
+      [{ label: 'a', value: 0 }],
+      [{ label: 'a', value: -1 }],
+      [{ label: 'a', value: 1 }],
+    ]
+    cases.forEach((segs) => {
+      const { container } = render(<DonutChart segments={segs} />)
+      expectNoNaN([
+        ...circleAttrs(container, 'r'),
+        ...circleAttrs(container, 'stroke-dasharray'),
+        ...circleAttrs(container, 'stroke-dashoffset'),
+        ...circleAttrs(container, 'stroke-width'),
+      ])
+    })
+  })
+
+  it('keeps the ring inside the box when thickness exceeds the size', () => {
+    const { container } = render(
+      <DonutChart segments={segments} size={40} thickness={999} />,
+    )
+    const r = Number(circleAttrs(container, 'r')[0])
+    const width = Number(circleAttrs(container, 'stroke-width')[0])
+    expect(width).toBe(20)
+    expect(r).toBe(10)
+    expect(r + width / 2).toBeLessThanOrEqual(20)
+  })
+
+  it('shows a legend with each label and value when asked', () => {
+    render(
+      <DonutChart
+        segments={segments}
+        showLegend
+        formatLegendValue={(s) => `$${s.value.toLocaleString()}`}
+      />,
+    )
+    expect(screen.getByText('Streaming')).toBeInTheDocument()
+    expect(screen.getByText('$22,400')).toBeInTheDocument()
+    expect(screen.getByText('$6,800')).toBeInTheDocument()
+  })
+
+  it('uses caller colours for the arcs and falls back to currentColor', () => {
+    const { container } = render(
+      <DonutChart segments={[{ label: 'a', value: 1, color: '#FF0000' }, { label: 'b', value: 1 }]} />,
+    )
+    const strokes = circleAttrs(container, 'stroke')
+    expect(strokes).toContain('#FF0000')
+    expect(strokes.filter((s) => s === 'currentColor').length).toBeGreaterThan(0)
+  })
+})

package/src/components/dashboard/index.ts

@@ -18,3 +18,15 @@ export type { PipelineFunnelProps, FunnelStage } from './PipelineFunnel'
 
 export { TopCampaigns } from './TopCampaigns'
 export type { TopCampaignsProps, TopCampaign } from './TopCampaigns'
+
+export { StatTile } from './StatTile'
+export type { StatTileProps, StatTileSize } from './StatTile'
+
+export { DeltaPill, resolveDeltaDirection, DELTA_UNAVAILABLE } from './DeltaPill'
+export type { DeltaPillProps, DeltaDirection } from './DeltaPill'
+
+export { DonutChart, donutSlices } from './DonutChart'
+export type { DonutChartProps, DonutSegment, DonutSlice } from './DonutChart'
+
+export { AreaTrend, areaTrendGeometry } from './AreaTrend'
+export type { AreaTrendProps } from './AreaTrend'

package/src/theme/contract.ts

@@ -17,6 +17,8 @@ export const THEME_TOKENS = {
     '--accent-foreground',
     '--destructive',
     '--destructive-foreground',
+    '--success',
+    '--success-foreground',
     '--border',
     '--input',
     '--ring',

package/src/theme/tailwind.config.js

@@ -28,6 +28,10 @@ module.exports = {
           DEFAULT: "hsl(var(--destructive))",
           foreground: "hsl(var(--destructive-foreground))",
         },
+        success: {
+          DEFAULT: "hsl(var(--success, 142.1 76.2% 36.3%))",
+          foreground: "hsl(var(--success-foreground, 210 40% 98%))",
+        },
         muted: {
           DEFAULT: "hsl(var(--muted))",
           foreground: "hsl(var(--muted-foreground))",

package/src/theme/tailwind.preset.ts

@@ -37,6 +37,12 @@ const preset: Partial<Config> = {
           DEFAULT: 'hsl(var(--destructive))',
           foreground: 'hsl(var(--destructive-foreground))',
         },
+        // Fallback channels keep `text-success` legible in apps that predate
+        // the token; apps that declare --success override it as usual.
+        success: {
+          DEFAULT: 'hsl(var(--success, 142.1 76.2% 36.3%))',
+          foreground: 'hsl(var(--success-foreground, 210 40% 98%))',
+        },
         border: 'hsl(var(--border))',
         input: 'hsl(var(--input))',
         ring: 'hsl(var(--ring))',

package/tailwind.preset.js

@@ -34,6 +34,12 @@ module.exports = {
           DEFAULT: 'hsl(var(--destructive))',
           foreground: 'hsl(var(--destructive-foreground))',
         },
+        // Fallback channels keep `text-success` legible in apps that predate
+        // the token; apps that declare --success override it as usual.
+        success: {
+          DEFAULT: 'hsl(var(--success, 142.1 76.2% 36.3%))',
+          foreground: 'hsl(var(--success-foreground, 210 40% 98%))',
+        },
         border: 'hsl(var(--border))',
         input: 'hsl(var(--input))',
         ring: 'hsl(var(--ring))',