@startsimpli/ui 0.4.137 → 0.4.139

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.137",
+  "version": "0.4.139",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -11,6 +11,7 @@
     "./foundry": "./src/foundry/index.ts",
     "./gantt": "./src/components/gantt/index.ts",
     "./gantt/styles": "./src/components/gantt/gantt.css",
+    "./charts": "./src/components/charts/index.ts",
     "./components": "./src/components/index.ts",
     "./error": "./src/components/error/index.ts",
     "./i18n": "./src/components/i18n/index.ts",
@@ -48,9 +49,9 @@
     "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.66",
     "@startsimpli/auth": "^0.4.38",
-    "@startsimpli/i18n": "^0.1.3",
-    "@startsimpli/api": "^0.5.66"
+    "@startsimpli/i18n": "^0.1.3"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -101,6 +102,7 @@
     "react-day-picker": "^9.14.0",
     "react-markdown": "^10.1.0",
     "react-syntax-highlighter": "^16.1.0",
+    "recharts": "^3.10.1",
     "remark-gfm": "^4.0.1",
     "tailwind-merge": "^2.6.1",
     "tailwindcss-animate": "^1.0.7",
@@ -124,8 +126,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/i18n": "0.1.3",
-    "@startsimpli/realtime": "0.0.2"
+    "@startsimpli/realtime": "0.0.2",
+    "@startsimpli/i18n": "0.1.3"
   },
   "keywords": [
     "ui",

package/src/components/charts/TimeSeriesChart.tsx

@@ -0,0 +1,305 @@
+'use client'
+
+import * as React from 'react'
+import {
+  CartesianGrid,
+  Line,
+  LineChart,
+  ReferenceLine,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from 'recharts'
+import { cn } from '../../lib/utils'
+import {
+  buildChartModel,
+  valueKey,
+  type ChartModel,
+  type ChartRow,
+  type TimeSeries,
+  type TimeSeriesMode,
+  type TimeSeriesUnit,
+} from './lib/series'
+import {
+  axisValueFormatter,
+  formatTick,
+  formatTooltipTime,
+  formatValue,
+  isDateOnly,
+  timeTicks,
+  valueTicks,
+} from './lib/format'
+
+export interface TimeSeriesReferenceLine {
+  /** Where the line sits, in the plotted unit (a drawdown % in drawdown mode). */
+  y: number
+  label?: string
+}
+
+export interface TimeSeriesChartProps {
+  series: TimeSeries[]
+  unit: TimeSeriesUnit
+  referenceLine?: TimeSeriesReferenceLine
+  /** `'drawdown'` plots each series as the % below its running peak. */
+  mode?: TimeSeriesMode
+  /** Plot height in px. The legend, when there is one, sits below it. */
+  height?: number
+  /** Overrides the generated description. */
+  ariaLabel?: string
+  className?: string
+}
+
+/**
+ * Series colours, in order, from the theme contract (theme/contract.css) — so
+ * they follow the app's brand and flip with `.dark` like every other surface.
+ * `--success` carries the same fallback channels as the Tailwind preset, for
+ * apps that predate the token.
+ */
+export const SERIES_COLORS = [
+  'hsl(var(--primary))',
+  'hsl(var(--muted-foreground))',
+  'hsl(var(--success, 142.1 76.2% 36.3%))',
+  'hsl(var(--destructive))',
+  'hsl(var(--foreground))',
+] as const
+
+/** After the palette runs out, series repeat its colours with a dash. */
+const DASHES = [undefined, '6 4', '2 3'] as const
+
+export function seriesStroke(index: number): { color: string; dash: string | undefined } {
+  const n = SERIES_COLORS.length
+  return {
+    color: SERIES_COLORS[index % n],
+    dash: DASHES[Math.floor(index / n) % DASHES.length],
+  }
+}
+
+const AXIS_TICK = { fill: 'hsl(var(--muted-foreground))', fontSize: 12 }
+const GRID_STROKE = 'hsl(var(--border))'
+
+function describe(model: ChartModel, mode: TimeSeriesMode, utc: boolean): string {
+  const kind = mode === 'drawdown' ? 'Drawdown chart' : 'Line chart'
+  if (!model.hasData) return `${kind}: no data`
+  const first = formatTooltipTime(model.times[0], utc, false)
+  const last = formatTooltipTime(model.times[model.times.length - 1], utc, false)
+  return `${kind} of ${model.names.join(', ')} from ${first} to ${last}`
+}
+
+interface TooltipBodyProps {
+  active?: boolean
+  label?: number | string
+  rowsByTime: Map<number, ChartRow>
+  names: string[]
+  unit: TimeSeriesUnit
+  utc: boolean
+  withTime: boolean
+}
+
+function TooltipBody({ active, label, rowsByTime, names, unit, utc, withTime }: TooltipBodyProps) {
+  if (!active || label === undefined) return null
+  const t = Number(label)
+  const row = rowsByTime.get(t)
+  if (!row) return null
+
+  // Every series with a sample here — a gap reads as a dash, a series with no
+  // sample at this instant is left out rather than shown as missing.
+  const entries = names
+    .map((name, i) => ({ name, i, v: row[valueKey(i)] }))
+    .filter((e) => e.v !== undefined)
+
+  return (
+    <div className="rounded-md border bg-popover px-3 py-2 text-xs text-popover-foreground shadow-md">
+      <div className="mb-1 font-medium">{formatTooltipTime(t, utc, withTime)}</div>
+      <ul className="space-y-0.5">
+        {entries.map((e) => (
+          <li key={e.i} className="flex items-center justify-between gap-4">
+            <span className="flex min-w-0 items-center gap-1.5">
+              <span
+                className="h-2 w-2 shrink-0 rounded-full"
+                style={{ backgroundColor: seriesStroke(e.i).color }}
+                aria-hidden="true"
+              />
+              <span className="truncate text-muted-foreground">{e.name}</span>
+            </span>
+            <span className="font-medium tabular-nums">
+              {typeof e.v === 'number' ? formatValue(e.v, unit) : '—'}
+            </span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+function SeriesLegend({ names }: { names: string[] }) {
+  return (
+    <ul className="flex flex-wrap items-center gap-x-4 gap-y-1 px-2 pt-2 text-xs text-muted-foreground">
+      {names.map((name, i) => {
+        const { color, dash } = seriesStroke(i)
+        return (
+          <li key={`${name}-${i}`} className="flex items-center gap-1.5">
+            <svg width="16" height="8" aria-hidden="true" className="shrink-0">
+              <line x1="0" y1="4" x2="16" y2="4" stroke={color} strokeWidth="2" strokeDasharray={dash} />
+            </svg>
+            <span>{name}</span>
+          </li>
+        )
+      })}
+    </ul>
+  )
+}
+
+/**
+ * One or more time series on a date axis. Values are formatted for `unit`;
+ * `null` points break the line instead of being joined across. With
+ * `mode="drawdown"` every series is shown as the % below its own running peak.
+ * Colours come from the theme tokens, so it follows light/dark with the app.
+ */
+export function TimeSeriesChart({
+  series,
+  unit,
+  referenceLine,
+  mode = 'line',
+  height = 300,
+  ariaLabel,
+  className,
+}: TimeSeriesChartProps) {
+  const model = React.useMemo(() => buildChartModel(series, mode, unit), [series, mode, unit])
+  const rowsByTime = React.useMemo(
+    () => new Map(model.rows.map((r) => [r.t, r] as const)),
+    [model],
+  )
+  const utc = isDateOnly(model.times)
+  const withTime = !utc && model.times.some((t) => {
+    const d = new Date(t)
+    return d.getHours() !== 0 || d.getMinutes() !== 0
+  })
+  const minT = model.times[0]
+  const maxT = model.times[model.times.length - 1]
+  const { ticks, step } = React.useMemo(
+    () => timeTicks(minT, maxT, utc),
+    [minT, maxT, utc],
+  )
+  const refY = referenceLine?.y
+  const yAxis = React.useMemo(() => {
+    let lo = model.min
+    let hi = model.max
+    if (typeof refY === 'number' && Number.isFinite(refY)) {
+      lo = Math.min(lo, refY)
+      hi = Math.max(hi, refY)
+    }
+    // A drawdown axis always tops out at 0 — "at the peak".
+    if (mode === 'drawdown') hi = 0
+    const { ticks: yTicks, step: yStep } = valueTicks(lo, hi)
+    return { ticks: yTicks, format: axisValueFormatter(model.unit, yTicks, yStep) }
+  }, [model, refY, mode])
+  const showLegend = series.length >= 2
+  const safeHeight = Math.max(height, 80)
+  const label = ariaLabel ?? describe(model, mode, utc)
+
+  if (!model.hasData) {
+    return (
+      <div
+        role="img"
+        aria-label={label}
+        className={cn(
+          'flex w-full items-center justify-center rounded-md border border-dashed text-sm text-muted-foreground',
+          className,
+        )}
+        style={{ height: safeHeight }}
+      >
+        No data
+      </div>
+    )
+  }
+
+  return (
+    <div role="figure" aria-label={label} className={cn('w-full', className)}>
+      <ResponsiveContainer width="100%" height={safeHeight}>
+        <LineChart data={model.rows} margin={{ top: 8, right: 16, bottom: 0, left: 0 }}>
+          <CartesianGrid stroke={GRID_STROKE} strokeDasharray="3 3" vertical={false} />
+          <XAxis
+            dataKey="t"
+            type="number"
+            scale="time"
+            domain={[minT, maxT]}
+            ticks={ticks}
+            tickFormatter={(t: number) => formatTick(t, step, utc)}
+            tick={AXIS_TICK}
+            stroke={GRID_STROKE}
+            tickLine={false}
+            minTickGap={16}
+          />
+          <YAxis
+            type="number"
+            ticks={yAxis.ticks}
+            domain={[yAxis.ticks[0], yAxis.ticks[yAxis.ticks.length - 1]]}
+            tickFormatter={(v: number) => yAxis.format(v)}
+            tick={AXIS_TICK}
+            stroke={GRID_STROKE}
+            tickLine={false}
+            axisLine={false}
+            width={64}
+            interval={0}
+          />
+          <Tooltip
+            cursor={{ stroke: GRID_STROKE }}
+            isAnimationActive={false}
+            content={(props) => (
+              <TooltipBody
+                active={props.active}
+                label={props.label as number | string | undefined}
+                rowsByTime={rowsByTime}
+                names={model.names}
+                unit={model.unit}
+                utc={utc}
+                withTime={withTime}
+              />
+            )}
+          />
+          {referenceLine && (
+            <ReferenceLine
+              y={referenceLine.y}
+              stroke="hsl(var(--muted-foreground))"
+              strokeDasharray="4 4"
+              ifOverflow="extendDomain"
+              label={
+                referenceLine.label
+                  ? {
+                      value: referenceLine.label,
+                      position: 'insideTopRight',
+                      fill: 'hsl(var(--muted-foreground))',
+                      fontSize: 12,
+                    }
+                  : undefined
+              }
+            />
+          )}
+          {model.segments.map((seg) => {
+            const { color, dash } = seriesStroke(seg.seriesIndex)
+            return (
+              <Line
+                key={seg.dataKey}
+                dataKey={seg.dataKey}
+                name={model.names[seg.seriesIndex]}
+                type="linear"
+                stroke={color}
+                strokeWidth={2}
+                strokeDasharray={dash}
+                // Within a run, step over instants this series has no sample
+                // at; runs themselves never join, which is what makes a null a gap.
+                connectNulls
+                dot={seg.single ? { r: 2.5, fill: color, stroke: color } : false}
+                activeDot={{ r: 3.5, fill: color, stroke: 'hsl(var(--background))' }}
+                isAnimationActive={false}
+                legendType="none"
+              />
+            )
+          })}
+        </LineChart>
+      </ResponsiveContainer>
+      {showLegend && <SeriesLegend names={model.names} />}
+    </div>
+  )
+}

package/src/components/charts/__tests__/TimeSeriesChart.test.tsx

@@ -0,0 +1,141 @@
+import { render, screen } from '@testing-library/react'
+import { TimeSeriesChart, SERIES_COLORS, seriesStroke } from '../TimeSeriesChart'
+import type { TimeSeries } from '../lib/series'
+
+// jsdom lays nothing out: recharts' ResponsiveContainer renders no chart at a
+// 0x0 size, and every tick label would measure 0 wide. Give the container a
+// real box and text a plausible one (8px a character), so recharts' own
+// overlap culling behaves as it does in a browser.
+function rect(width: number, height: number): DOMRect {
+  return { width, height, top: 0, left: 0, right: width, bottom: height, x: 0, y: 0, toJSON: () => ({}) } as DOMRect
+}
+let rectSpy: jest.SpyInstance
+beforeAll(() => {
+  rectSpy = jest
+    .spyOn(HTMLElement.prototype, 'getBoundingClientRect')
+    .mockImplementation(function (this: HTMLElement) {
+      if (this.classList.contains('recharts-responsive-container')) return rect(800, 300)
+      return rect((this.textContent ?? '').length * 8, 14)
+    })
+})
+afterAll(() => rectSpy.mockRestore())
+
+/** Tick labels on one axis; recharts splits a label into one tspan per word. */
+function tickLabels(container: HTMLElement, axis: 'x' | 'y'): string[] {
+  return Array.from(
+    container.querySelectorAll(`.recharts-${axis}Axis-tick-labels .recharts-cartesian-axis-tick-value`),
+  ).map((n) =>
+    Array.from(n.querySelectorAll('tspan'))
+      .map((s) => s.textContent)
+      .join(' '),
+  )
+}
+
+const strategy: TimeSeries = {
+  name: 'Strategy',
+  points: [
+    { t: '2026-01-05', v: 100_000 },
+    { t: '2026-01-06', v: 104_000 },
+    { t: '2026-01-07', v: null },
+    { t: '2026-01-08', v: 98_000 },
+    { t: '2026-01-09', v: 110_000 },
+  ],
+}
+
+const holding: TimeSeries = {
+  name: 'Buy & hold',
+  points: [
+    { t: '2026-01-05', v: 100_000 },
+    { t: '2026-01-06', v: 101_000 },
+    { t: '2026-01-07', v: 99_000 },
+    { t: '2026-01-08', v: 97_000 },
+    { t: '2026-01-09', v: 102_000 },
+  ],
+}
+
+function linePaths(container: HTMLElement) {
+  return Array.from(container.querySelectorAll('path.recharts-line-curve'))
+}
+
+describe('TimeSeriesChart', () => {
+  it('draws one stroke per unbroken run, so a null leaves a gap', () => {
+    const { container } = render(<TimeSeriesChart series={[strategy]} unit="$" />)
+    // Strategy breaks at Jan 7: two runs, two strokes, nothing joining them.
+    expect(linePaths(container)).toHaveLength(2)
+  })
+
+  it('colours series from theme tokens, never a fixed palette', () => {
+    const { container } = render(<TimeSeriesChart series={[strategy, holding]} unit="$" />)
+    const strokes = linePaths(container).map((p) => p.getAttribute('stroke'))
+    expect(strokes.length).toBeGreaterThan(0)
+    for (const stroke of strokes) {
+      expect(stroke).toMatch(/^hsl\(var\(--[a-z-]+/)
+    }
+    expect(new Set(strokes)).toEqual(new Set([SERIES_COLORS[0], SERIES_COLORS[1]]))
+  })
+
+  it('shows a legend for two or more series and none for one', () => {
+    const { rerender } = render(<TimeSeriesChart series={[strategy, holding]} unit="$" />)
+    expect(screen.getByText('Strategy')).toBeInTheDocument()
+    expect(screen.getByText('Buy & hold')).toBeInTheDocument()
+
+    rerender(<TimeSeriesChart series={[strategy]} unit="$" />)
+    expect(screen.queryByText('Strategy')).not.toBeInTheDocument()
+  })
+
+  it('labels the date axis in calendar terms and the value axis in the unit', () => {
+    const { container } = render(<TimeSeriesChart series={[strategy]} unit="$" />)
+    expect(tickLabels(container, 'x')).toContain('Jan 5')
+    const y = tickLabels(container, 'y')
+    expect(y.length).toBeGreaterThan(1)
+    expect(y.every((t) => /^\$\d+(\.\d+)?K$/.test(t))).toBe(true)
+  })
+
+  it('draws a labelled reference line', () => {
+    const { container } = render(
+      <TimeSeriesChart
+        series={[strategy]}
+        unit="$"
+        referenceLine={{ y: 100_000, label: 'Start' }}
+      />,
+    )
+    expect(container.querySelector('.recharts-reference-line')).not.toBeNull()
+    expect(screen.getByText('Start')).toBeInTheDocument()
+  })
+
+  it('plots drawdown in % on an axis that tops out at 0', () => {
+    const { container } = render(
+      <TimeSeriesChart series={[strategy]} unit="$" mode="drawdown" />,
+    )
+    expect(screen.getByRole('figure')).toHaveAccessibleName(/^Drawdown chart of Strategy/)
+    const yTicks = tickLabels(container, 'y')
+
+    expect(yTicks.length).toBeGreaterThan(0)
+    expect(yTicks.every((t) => t.endsWith('%'))).toBe(true)
+    expect(yTicks).toContain('0%')
+  })
+
+  it('describes itself for assistive tech', () => {
+    render(<TimeSeriesChart series={[strategy, holding]} unit="$" />)
+    expect(screen.getByRole('figure')).toHaveAccessibleName(
+      'Line chart of Strategy, Buy & hold from Jan 5, 2026 to Jan 9, 2026',
+    )
+  })
+
+  it('renders an empty state when there is nothing to plot', () => {
+    render(
+      <TimeSeriesChart series={[{ name: 'Empty', points: [{ t: '2026-01-05', v: null }] }]} unit="%" />,
+    )
+    expect(screen.getByRole('img')).toHaveAccessibleName('Line chart: no data')
+    expect(screen.getByText('No data')).toBeInTheDocument()
+  })
+})
+
+describe('seriesStroke', () => {
+  it('cycles the token palette and dashes the repeats', () => {
+    const n = SERIES_COLORS.length
+    expect(seriesStroke(0)).toEqual({ color: SERIES_COLORS[0], dash: undefined })
+    expect(seriesStroke(n)).toEqual({ color: SERIES_COLORS[0], dash: '6 4' })
+    expect(seriesStroke(n + 1).color).toBe(SERIES_COLORS[1])
+  })
+})

package/src/components/charts/__tests__/format.test.ts

@@ -0,0 +1,159 @@
+import {
+  axisValueFormatter,
+  formatTick,
+  formatTooltipTime,
+  formatValue,
+  isDateOnly,
+  timeTicks,
+  valueTicks,
+} from '../lib/format'
+
+describe('formatValue', () => {
+  it('formats dollars with cents below $1,000 and whole dollars above', () => {
+    expect(formatValue(12.5, '$')).toBe('$12.50')
+    expect(formatValue(319517.4, '$')).toBe('$319,517')
+    expect(formatValue(-1234, '$')).toBe('-$1,234')
+  })
+
+  it('formats % values as percentage points, not fractions', () => {
+    expect(formatValue(12.345, '%')).toBe('12.3%')
+    expect(formatValue(-3.14159, '%')).toBe('-3.14%')
+    expect(formatValue(250.4, '%')).toBe('250%')
+  })
+
+  it('formats plain numbers with grouping', () => {
+    expect(formatValue(1234.567, 'number')).toBe('1,235')
+    expect(formatValue(0.12345, 'number')).toBe('0.12')
+  })
+})
+
+describe('formatValue at zero', () => {
+  it('never renders negative zero', () => {
+    expect(formatValue(-0.0001, '%')).toBe('0%')
+    expect(formatValue(-0.001, '$')).toBe('$0.00')
+  })
+})
+
+describe('valueTicks', () => {
+  it('covers the range with round multiples of a nice step', () => {
+    const { ticks, step } = valueTicks(-8, 190)
+    expect(step.value).toBe(50)
+    expect(ticks).toEqual([-50, 0, 50, 100, 150, 200])
+  })
+
+  it('keeps fractional steps exact', () => {
+    const { ticks, step } = valueTicks(0.1, 0.9)
+    expect(step).toEqual({ value: 0.2, decimals: 1 })
+    expect(ticks).toEqual([0, 0.2, 0.4, 0.6, 0.8, 1])
+  })
+
+  it('needs one more decimal for a 2.5 step', () => {
+    expect(valueTicks(30.3, 31.3).step).toEqual({ value: 0.25, decimals: 2 })
+  })
+
+  it('opens a band around a flat series', () => {
+    const { ticks } = valueTicks(100, 100)
+    expect(ticks[0]).toBeLessThan(100)
+    expect(ticks[ticks.length - 1]).toBeGreaterThan(100)
+  })
+})
+
+describe('axisValueFormatter', () => {
+  const labels = (unit: '$' | '%' | 'number', min: number, max: number) => {
+    const { ticks, step } = valueTicks(min, max)
+    const format = axisValueFormatter(unit, ticks, step)
+    return ticks.map(format)
+  }
+
+  it('compacts by the largest tick and keeps one precision across labels', () => {
+    expect(labels('$', 60_000, 300_000)).toEqual(['$0', '$100K', '$200K', '$300K'])
+    expect(labels('$', 30.3, 31.3)).toEqual(['$30.25', '$30.50', '$30.75', '$31.00', '$31.25', '$31.50'])
+    expect(labels('number', 0, 2_500_000)).toEqual(['0', '1M', '2M', '3M'])
+    expect(labels('number', 0, 1_800_000)).toEqual(['0', '0.5M', '1.0M', '1.5M', '2.0M'])
+  })
+
+  it('keeps cents on small dollar axes', () => {
+    expect(labels('$', 1, 5)).toEqual(['$1.00', '$2.00', '$3.00', '$4.00', '$5.00'])
+  })
+
+  it('suffixes percentages', () => {
+    expect(labels('%', -24, 0)).toEqual(['-30%', '-20%', '-10%', '0%'])
+    expect(labels('%', 0, 25_000)).toEqual(['0%', '10K%', '20K%', '30K%'])
+  })
+})
+
+describe('isDateOnly', () => {
+  it('is true only when every timestamp is midnight UTC', () => {
+    expect(isDateOnly([Date.UTC(2026, 0, 1), Date.UTC(2026, 0, 2)])).toBe(true)
+    expect(isDateOnly([Date.UTC(2026, 0, 1), Date.UTC(2026, 0, 2, 14, 30)])).toBe(false)
+    expect(isDateOnly([])).toBe(false)
+  })
+})
+
+describe('timeTicks', () => {
+  it('puts a month of daily data on Mondays', () => {
+    const { ticks, step } = timeTicks(Date.UTC(2026, 0, 1), Date.UTC(2026, 0, 31), true)
+    expect(step).toEqual({ unit: 'day', count: 7 })
+    // 2026-01-05 is a Monday.
+    expect(ticks[0]).toBe(Date.UTC(2026, 0, 5))
+    expect(ticks.every((t) => new Date(t).getUTCDay() === 1)).toBe(true)
+  })
+
+  it('puts two years on quarter starts', () => {
+    const { ticks, step } = timeTicks(Date.UTC(2024, 1, 10), Date.UTC(2026, 1, 10), true)
+    expect(step.unit).toBe('month')
+    expect(ticks.length).toBeLessThanOrEqual(6)
+    for (const t of ticks) {
+      const d = new Date(t)
+      expect(d.getUTCDate()).toBe(1)
+      expect(d.getUTCMonth() % step.count).toBe(0)
+    }
+  })
+
+  it('puts a decade on year starts', () => {
+    const { ticks, step } = timeTicks(Date.UTC(2016, 3, 1), Date.UTC(2026, 3, 1), true)
+    expect(step.unit).toBe('month')
+    expect(step.count % 12).toBe(0)
+    expect(ticks.every((t) => new Date(t).getUTCMonth() === 0)).toBe(true)
+  })
+
+  it('puts an intraday session on round local times', () => {
+    const open = new Date(2026, 0, 5, 9, 30).getTime()
+    const close = new Date(2026, 0, 5, 16, 0).getTime()
+    const { ticks, step } = timeTicks(open, close, false)
+    expect(step.unit).toBe('minute')
+    expect(ticks.length).toBeGreaterThan(1)
+    expect(ticks.length).toBeLessThanOrEqual(6)
+    for (const t of ticks) {
+      const d = new Date(t)
+      expect((d.getHours() * 60 + d.getMinutes()) % step.count).toBe(0)
+      expect(t).toBeGreaterThanOrEqual(open)
+      expect(t).toBeLessThanOrEqual(close)
+    }
+  })
+
+  it('handles a single instant', () => {
+    expect(timeTicks(5, 5, true).ticks).toEqual([5])
+  })
+
+  it('respects maxTicks', () => {
+    const { ticks } = timeTicks(Date.UTC(2020, 0, 1), Date.UTC(2026, 0, 1), true, 4)
+    expect(ticks.length).toBeLessThanOrEqual(4)
+    expect(ticks.length).toBeGreaterThan(0)
+  })
+})
+
+describe('formatTick / formatTooltipTime', () => {
+  it('labels a tick as finely as its step', () => {
+    const t = Date.UTC(2026, 2, 1)
+    expect(formatTick(t, { unit: 'day', count: 7 }, true)).toBe('Mar 1')
+    expect(formatTick(t, { unit: 'month', count: 3 }, true)).toBe('Mar 2026')
+    expect(formatTick(t, { unit: 'month', count: 12 }, true)).toBe('2026')
+    expect(formatTick(t, { unit: 'minute', count: 60 }, true)).toBe('Mar 1')
+    expect(formatTick(Date.UTC(2026, 2, 1, 14, 30), { unit: 'minute', count: 30 }, true)).toBe('2:30 PM')
+  })
+
+  it('labels date-only data in UTC so it never slips to the previous day', () => {
+    expect(formatTooltipTime(Date.UTC(2026, 0, 5), true, false)).toBe('Jan 5, 2026')
+  })
+})

package/src/components/charts/__tests__/series.test.ts

@@ -0,0 +1,168 @@
+import {
+  buildChartModel,
+  normalizePoints,
+  toDrawdown,
+  toEpochMs,
+  valueKey,
+} from '../lib/series'
+
+const day = (d: number) => Date.UTC(2026, 0, d)
+
+describe('toEpochMs', () => {
+  it('reads Dates, epoch ms and ISO strings to the same instant', () => {
+    const ms = Date.UTC(2026, 0, 5)
+    expect(toEpochMs(new Date(ms))).toBe(ms)
+    expect(toEpochMs(ms)).toBe(ms)
+    expect(toEpochMs('2026-01-05')).toBe(ms)
+  })
+
+  it('returns null for an unreadable timestamp', () => {
+    expect(toEpochMs('not a date')).toBeNull()
+    expect(toEpochMs(Number.NaN)).toBeNull()
+    expect(toEpochMs(new Date('nope'))).toBeNull()
+  })
+})
+
+describe('normalizePoints', () => {
+  it('sorts by time, drops unreadable timestamps, and lets the later duplicate win', () => {
+    const out = normalizePoints([
+      { t: day(3), v: 3 },
+      { t: 'garbage', v: 99 },
+      { t: day(1), v: 1 },
+      { t: day(3), v: 30 },
+    ])
+    expect(out).toEqual([
+      { t: day(1), v: 1 },
+      { t: day(3), v: 30 },
+    ])
+  })
+
+  it('treats a non-finite value as a gap', () => {
+    expect(normalizePoints([{ t: day(1), v: Number.NaN }])).toEqual([{ t: day(1), v: null }])
+  })
+})
+
+describe('toDrawdown', () => {
+  it('is 0 at each new high and the % below the running peak otherwise', () => {
+    const out = toDrawdown(
+      [
+        { t: 1, v: 100 },
+        { t: 2, v: 120 },
+        { t: 3, v: 90 },
+        { t: 4, v: 130 },
+      ],
+      '$',
+    )
+    expect(out.map((p) => p.v)).toEqual([0, 0, -25, 0])
+  })
+
+  it('never yields -0 at a new high', () => {
+    const [p] = toDrawdown([{ t: 1, v: 50 }], 'number')
+    expect(Object.is(p.v, -0)).toBe(false)
+  })
+
+  it('reads % values as cumulative returns: +50% -> +20% is a 20% drawdown', () => {
+    const out = toDrawdown(
+      [
+        { t: 1, v: 50 },
+        { t: 2, v: 20 },
+      ],
+      '%',
+    )
+    expect(out[1].v).toBeCloseTo(-20, 10)
+  })
+
+  it('keeps a gap a gap and does not reset the peak across it', () => {
+    const out = toDrawdown(
+      [
+        { t: 1, v: 200 },
+        { t: 2, v: null },
+        { t: 3, v: 100 },
+      ],
+      '$',
+    )
+    expect(out.map((p) => p.v)).toEqual([0, null, -50])
+  })
+
+  it('has no % below a non-positive peak, so those points become gaps', () => {
+    const out = toDrawdown(
+      [
+        { t: 1, v: -5 },
+        { t: 2, v: -10 },
+        { t: 3, v: 10 },
+        { t: 4, v: 5 },
+      ],
+      'number',
+    )
+    expect(out.map((p) => p.v)).toEqual([null, null, 0, -50])
+  })
+})
+
+describe('buildChartModel', () => {
+  it('merges series onto one row per distinct timestamp', () => {
+    const model = buildChartModel(
+      [
+        { name: 'A', points: [{ t: day(1), v: 1 }, { t: day(2), v: 2 }] },
+        { name: 'B', points: [{ t: day(2), v: 20 }, { t: day(3), v: 30 }] },
+      ],
+      'line',
+      'number',
+    )
+    expect(model.times).toEqual([day(1), day(2), day(3)])
+    expect(model.rows[1][valueKey(0)]).toBe(2)
+    expect(model.rows[1][valueKey(1)]).toBe(20)
+    // A has no sample on day 3 — absent, not a gap.
+    expect(model.rows[2][valueKey(0)]).toBeUndefined()
+    expect(model.names).toEqual(['A', 'B'])
+    expect(model.hasData).toBe(true)
+  })
+
+  it('splits a series into separate runs at every null so the gap is not bridged', () => {
+    const model = buildChartModel(
+      [
+        {
+          name: 'A',
+          points: [
+            { t: day(1), v: 1 },
+            { t: day(2), v: 2 },
+            { t: day(3), v: null },
+            { t: day(4), v: 4 },
+            { t: day(5), v: 5 },
+          ],
+        },
+      ],
+      'line',
+      'number',
+    )
+    expect(model.segments.map((s) => s.dataKey)).toEqual(['s0_0', 's0_1'])
+    // The first run holds no value past the gap and the second none before it.
+    expect(model.rows.map((r) => r.s0_0)).toEqual([1, 2, undefined, undefined, undefined])
+    expect(model.rows.map((r) => r.s0_1)).toEqual([undefined, undefined, undefined, 4, 5])
+    expect(model.rows[2][valueKey(0)]).toBeNull()
+  })
+
+  it('marks a one-point run so it can be drawn as a dot', () => {
+    const model = buildChartModel(
+      [{ name: 'A', points: [{ t: day(1), v: null }, { t: day(2), v: 7 }, { t: day(3), v: null }] }],
+      'line',
+      '$',
+    )
+    expect(model.segments).toEqual([{ dataKey: 's0_0', seriesIndex: 0, single: true }])
+  })
+
+  it('reports no data when nothing is finite', () => {
+    const model = buildChartModel([{ name: 'A', points: [{ t: day(1), v: null }] }], 'line', '$')
+    expect(model.hasData).toBe(false)
+    expect(model.segments).toEqual([])
+  })
+
+  it('shows drawdown in % whatever the input unit', () => {
+    const model = buildChartModel(
+      [{ name: 'Equity', points: [{ t: day(1), v: 100 }, { t: day(2), v: 80 }] }],
+      'drawdown',
+      '$',
+    )
+    expect(model.unit).toBe('%')
+    expect(model.rows[1][valueKey(0)]).toBeCloseTo(-20, 10)
+  })
+})

package/src/components/charts/index.ts

@@ -0,0 +1,13 @@
+// Charts live behind their own subpath (`@startsimpli/ui/charts`) so recharts
+// is only bundled by apps that draw one.
+export { TimeSeriesChart, SERIES_COLORS, seriesStroke } from './TimeSeriesChart'
+export type { TimeSeriesChartProps, TimeSeriesReferenceLine } from './TimeSeriesChart'
+export type {
+  TimeSeries,
+  TimeSeriesPoint,
+  TimeSeriesUnit,
+  TimeSeriesMode,
+  TimeValue,
+} from './lib/series'
+export { buildChartModel, normalizePoints, toDrawdown, toEpochMs } from './lib/series'
+export { formatValue } from './lib/format'

package/src/components/charts/lib/format.ts

@@ -0,0 +1,259 @@
+/**
+ * Value + time formatting for TimeSeriesChart. Pure, en-US like the rest of the
+ * package's formatters (utils/index.ts), so output is the same on every
+ * machine.
+ */
+import type { TimeSeriesUnit } from './series'
+
+const LOCALE = 'en-US'
+
+/**
+ * `v` in the unit with exactly `digits` decimals. A value that rounds to zero
+ * prints as zero — never `-0` or `-$0.00`.
+ */
+function fixed(v: number, unit: TimeSeriesUnit, digits: number, minDigits = digits): string {
+  const value = Math.abs(v) < 0.5 * 10 ** -digits ? 0 : v
+  const text = new Intl.NumberFormat(LOCALE, {
+    minimumFractionDigits: minDigits,
+    maximumFractionDigits: digits,
+    ...(unit === '$' ? { style: 'currency', currency: 'USD' } : {}),
+  }).format(value)
+  return unit === '%' ? `${text}%` : text
+}
+
+/** Full value, for the tooltip: `$1,234`, `$12.50`, `12.5%`, `1,234.57`. */
+export function formatValue(v: number, unit: TimeSeriesUnit): string {
+  const abs = Math.abs(v)
+  if (unit === '$') return fixed(v, unit, abs >= 1000 ? 0 : 2)
+  if (unit === '%') return fixed(v, unit, abs >= 100 ? 0 : abs >= 10 ? 1 : 2, 0)
+  return fixed(v, unit, abs >= 1000 ? 0 : 2, 0)
+}
+
+/** A "nice" tick step: 1, 2, 2.5 or 5 times a power of ten. */
+interface NiceStep {
+  value: number
+  /** Decimals needed to print every multiple of `value` exactly. */
+  decimals: number
+}
+
+function niceStep(rough: number): NiceStep {
+  const exp = Math.floor(Math.log10(rough))
+  const base = 10 ** exp
+  const m = [1, 2, 2.5, 5, 10].find((c) => c * base >= rough * (1 - 1e-9)) ?? 10
+  const k = m === 10 ? exp + 1 : exp
+  return {
+    value: m * base,
+    decimals: Math.max(0, -k + (m === 2.5 ? 1 : 0)),
+  }
+}
+
+/**
+ * Value-axis ticks over `[min, max]`: round multiples of a nice step, about
+ * `count` of them, covering the range and no more. Done here rather than by
+ * recharts so the labels can share one precision (`$30.80` / `$31.00`, not
+ * `$30.8` / `$31`).
+ */
+export function valueTicks(
+  min: number,
+  max: number,
+  count = 5,
+): { ticks: number[]; step: NiceStep } {
+  let lo = min
+  let hi = max
+  if (!(hi > lo)) {
+    // One value (or a flat line): open a band around it so it has an axis.
+    const pad = Math.abs(lo) > 0 ? Math.abs(lo) * 0.1 : 1
+    lo -= pad
+    hi += pad
+  }
+  const step = niceStep((hi - lo) / Math.max(count - 1, 1))
+  const first = Math.floor(lo / step.value + 1e-9)
+  const last = Math.ceil(hi / step.value - 1e-9)
+  const ticks: number[] = []
+  for (let i = first; i <= last; i += 1) {
+    // Multiply rather than accumulate, so 0.1-steps don't drift to 0.30000000000000004.
+    ticks.push(Number((i * step.value).toFixed(step.decimals)))
+  }
+  return { ticks, step }
+}
+
+const COMPACT = [
+  { at: 1e9, suffix: 'B' },
+  { at: 1e6, suffix: 'M' },
+  { at: 1e3, suffix: 'K' },
+] as const
+
+/**
+ * Formatter for the value-axis ticks from `valueTicks`: compacted to K/M/B by
+ * the largest tick, every label at the precision the step needs —
+ * `$300K`, `$30.80`, `-20%`, `12.5K`.
+ */
+export function axisValueFormatter(
+  unit: TimeSeriesUnit,
+  ticks: number[],
+  step: NiceStep,
+): (v: number) => string {
+  const maxAbs = Math.max(0, ...ticks.map((t) => Math.abs(t)))
+  const scale = COMPACT.find((c) => maxAbs >= c.at)
+  if (!scale) {
+    // Uncompacted dollars below $10 keep their cents.
+    const digits = unit === '$' && maxAbs < 10 ? Math.max(step.decimals, 2) : step.decimals
+    return (v) => fixed(v, unit, digits)
+  }
+  const digits = Math.max(0, niceStep(step.value / scale.at).decimals)
+  return (v) => {
+    // Zero is zero in any scale: `$0`, not `$0K`.
+    if (v === 0) return fixed(0, unit, 0)
+    const text = fixed(v / scale.at, unit === '%' ? 'number' : unit, digits)
+    return `${text}${scale.suffix}${unit === '%' ? '%' : ''}`
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Time
+// ---------------------------------------------------------------------------
+
+const MINUTE = 60_000
+const HOUR = 60 * MINUTE
+const DAY = 24 * HOUR
+
+/** A tick interval: a fixed number of minutes/days, or calendar months. */
+export type TickStep =
+  | { unit: 'minute'; count: number }
+  | { unit: 'day'; count: number }
+  | { unit: 'month'; count: number }
+
+const STEPS: TickStep[] = [
+  ...[1, 5, 15, 30, 60, 180, 360, 720].map((count) => ({ unit: 'minute' as const, count })),
+  ...[1, 2, 7, 14].map((count) => ({ unit: 'day' as const, count })),
+  ...[1, 3, 6, 12, 24, 60, 120, 240, 600].map((count) => ({ unit: 'month' as const, count })),
+]
+
+function approxMs(step: TickStep): number {
+  if (step.unit === 'minute') return step.count * MINUTE
+  if (step.unit === 'day') return step.count * DAY
+  return step.count * 30.44 * DAY
+}
+
+/**
+ * Whether every timestamp is midnight UTC — i.e. the data is date-only
+ * (`'2026-01-05'` parses to midnight UTC). Such data is labelled in UTC; in
+ * local time a US viewer would see every bar under the previous day.
+ */
+export function isDateOnly(times: number[]): boolean {
+  return times.length > 0 && times.every((t) => t % DAY === 0)
+}
+
+/** Calendar accessors in either UTC or the viewer's zone. */
+function calendar(utc: boolean) {
+  return {
+    parts(t: number) {
+      const d = new Date(t)
+      return utc
+        ? { y: d.getUTCFullYear(), mo: d.getUTCMonth(), d: d.getUTCDate(), h: d.getUTCHours(), mi: d.getUTCMinutes(), dow: d.getUTCDay() }
+        : { y: d.getFullYear(), mo: d.getMonth(), d: d.getDate(), h: d.getHours(), mi: d.getMinutes(), dow: d.getDay() }
+    },
+    make(y: number, mo: number, d: number, h = 0, mi = 0): number {
+      return utc ? Date.UTC(y, mo, d, h, mi) : new Date(y, mo, d, h, mi).getTime()
+    },
+  }
+}
+
+/** Tick instants for one step, aligned to round calendar boundaries. */
+function ticksForStep(min: number, max: number, step: TickStep, utc: boolean, limit: number): number[] {
+  const cal = calendar(utc)
+  const p = cal.parts(min)
+  const out: number[] = []
+  const push = (t: number) => {
+    if (t >= min && t <= max) out.push(t)
+    return out.length <= limit && t <= max
+  }
+
+  if (step.unit === 'minute') {
+    // Minutes since local midnight, rounded up to a multiple of the step.
+    const sinceMidnight = p.h * 60 + p.mi
+    const first = Math.ceil(sinceMidnight / step.count) * step.count
+    for (let m = first; ; m += step.count) {
+      if (!push(cal.make(p.y, p.mo, p.d, 0, m))) break
+    }
+    return out
+  }
+
+  if (step.unit === 'day') {
+    let day = p.d
+    if (cal.make(p.y, p.mo, day) < min) day += 1
+    // Weekly steps start on a Monday so the labels line up week to week.
+    if (step.count >= 7) {
+      const dow = cal.parts(cal.make(p.y, p.mo, day)).dow
+      day += (8 - dow) % 7
+    }
+    for (let d = day; ; d += step.count) {
+      if (!push(cal.make(p.y, p.mo, d))) break
+    }
+    return out
+  }
+
+  // Months: start on a month whose index is a multiple of the step, so a
+  // quarterly axis reads Jan/Apr/Jul/Oct and a 5-year axis 2020/2025/2030.
+  let month = p.y * 12 + p.mo
+  if (cal.make(p.y, p.mo, 1) < min) month += 1
+  month = Math.ceil(month / step.count) * step.count
+  for (let m = month; ; m += step.count) {
+    if (!push(cal.make(Math.floor(m / 12), m % 12, 1))) break
+  }
+  return out
+}
+
+/**
+ * Evenly spaced, calendar-aligned ticks across `[min, max]`: the finest step
+ * that yields at most `maxTicks` of them (midnights, Mondays, month or year
+ * starts — never "every 4.3 days from the first sample").
+ */
+export function timeTicks(
+  min: number,
+  max: number,
+  utc: boolean,
+  maxTicks = 6,
+): { ticks: number[]; step: TickStep } {
+  const cap = Math.max(maxTicks, 2)
+  if (!(max > min)) return { ticks: Number.isFinite(min) ? [min] : [], step: STEPS[0] }
+  const span = max - min
+  for (const step of STEPS) {
+    if (span / approxMs(step) > cap + 1) continue
+    const ticks = ticksForStep(min, max, step, utc, cap)
+    if (ticks.length <= cap && ticks.length > 0) return { ticks, step }
+  }
+  const step = STEPS[STEPS.length - 1]
+  return { ticks: ticksForStep(min, max, step, utc, cap), step }
+}
+
+/** Label for an axis tick, as fine as the step it sits on. */
+export function formatTick(t: number, step: TickStep, utc: boolean): string {
+  const timeZone = utc ? 'UTC' : undefined
+  if (step.unit === 'minute') {
+    const p = calendar(utc).parts(t)
+    // A tick on midnight names the day, so a multi-day intraday axis stays readable.
+    if (p.h === 0 && p.mi === 0) {
+      return new Intl.DateTimeFormat(LOCALE, { month: 'short', day: 'numeric', timeZone }).format(t)
+    }
+    return new Intl.DateTimeFormat(LOCALE, { hour: 'numeric', minute: '2-digit', timeZone }).format(t)
+  }
+  if (step.unit === 'day') {
+    return new Intl.DateTimeFormat(LOCALE, { month: 'short', day: 'numeric', timeZone }).format(t)
+  }
+  if (step.count < 12) {
+    return new Intl.DateTimeFormat(LOCALE, { month: 'short', year: 'numeric', timeZone }).format(t)
+  }
+  return new Intl.DateTimeFormat(LOCALE, { year: 'numeric', timeZone }).format(t)
+}
+
+/** Label for the tooltip: the full date, plus the time when the data has one. */
+export function formatTooltipTime(t: number, utc: boolean, withTime: boolean): string {
+  return new Intl.DateTimeFormat(LOCALE, {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    ...(withTime ? { hour: 'numeric', minute: '2-digit' } : {}),
+    timeZone: utc ? 'UTC' : undefined,
+  }).format(t)
+}

package/src/components/charts/lib/series.ts

@@ -0,0 +1,183 @@
+/**
+ * Pure data shaping for TimeSeriesChart — no React, no recharts, so every rule
+ * here is unit-tested on its own.
+ */
+
+/** A timestamp: a Date, epoch milliseconds, or any string `Date.parse` reads. */
+export type TimeValue = string | number | Date
+
+export interface TimeSeriesPoint {
+  t: TimeValue
+  /** `null` is a gap: the line breaks there instead of joining its neighbours. */
+  v: number | null
+}
+
+export interface TimeSeries {
+  name: string
+  points: TimeSeriesPoint[]
+}
+
+/**
+ * How a value reads. `'%'` values are percentage POINTS — pass `12.5` for
+ * 12.5%, not `0.125`. `'$'` is US dollars.
+ */
+export type TimeSeriesUnit = '%' | '$' | 'number'
+
+/**
+ * `'line'` plots the values as given. `'drawdown'` plots each series as the
+ * percentage it sits below its own running peak (0 at a new high, negative
+ * otherwise).
+ */
+export type TimeSeriesMode = 'line' | 'drawdown'
+
+/** A point after parsing: epoch ms + a finite value or a gap. */
+export interface NormalizedPoint {
+  t: number
+  v: number | null
+}
+
+/** Epoch ms for a timestamp, or null when it cannot be read. */
+export function toEpochMs(t: TimeValue): number | null {
+  const ms = t instanceof Date ? t.getTime() : typeof t === 'number' ? t : Date.parse(t)
+  return Number.isFinite(ms) ? ms : null
+}
+
+/**
+ * Parse, sort and de-duplicate one series. Points whose timestamp cannot be
+ * read are dropped (there is nowhere to put them); a non-finite value becomes a
+ * gap. Two points at the same instant: the later one in the input wins.
+ */
+export function normalizePoints(points: TimeSeriesPoint[]): NormalizedPoint[] {
+  const byTime = new Map<number, number | null>()
+  for (const p of points) {
+    const t = toEpochMs(p.t)
+    if (t === null) continue
+    byTime.set(t, typeof p.v === 'number' && Number.isFinite(p.v) ? p.v : null)
+  }
+  return [...byTime.entries()].sort((a, b) => a[0] - b[0]).map(([t, v]) => ({ t, v }))
+}
+
+/**
+ * Each point as the percentage below the running peak of everything before it.
+ *
+ * For `'$'` and `'number'` the peak is taken over the raw values. For `'%'`
+ * the values are read as cumulative returns and the peak is taken over the
+ * growth they imply (`1 + v/100`): falling from +50% to +20% is a 20%
+ * drawdown, not a 60% one.
+ *
+ * A gap stays a gap and does not reset the peak. While the peak is not
+ * positive there is no meaningful "% below it", so those points become gaps.
+ */
+export function toDrawdown(points: NormalizedPoint[], unit: TimeSeriesUnit): NormalizedPoint[] {
+  let peak: number | null = null
+  return points.map(({ t, v }) => {
+    if (v === null) return { t, v: null }
+    const level = unit === '%' ? 1 + v / 100 : v
+    if (peak === null || level > peak) peak = level
+    if (!(peak > 0)) return { t, v: null }
+    const dd = (level / peak - 1) * 100
+    // A new high is exactly 0, never -0 (which would format as "-0%").
+    return { t, v: dd === 0 ? 0 : dd }
+  })
+}
+
+/** One recharts row per distinct timestamp across all series. */
+export interface ChartRow {
+  t: number
+  [key: string]: number | null | undefined
+}
+
+/**
+ * One drawn line: a contiguous run of a series between gaps. A series with
+ * gaps is several of these, so a gap is a real break in the stroke while a
+ * timestamp the series simply has no sample at (because another series does)
+ * is stepped over.
+ */
+export interface ChartSegment {
+  dataKey: string
+  seriesIndex: number
+  /** A run of one point — there is no stroke to draw, so it needs a dot. */
+  single: boolean
+}
+
+export interface ChartModel {
+  rows: ChartRow[]
+  segments: ChartSegment[]
+  names: string[]
+  /** The unit values are DISPLAYED in — always `'%'` in drawdown mode. */
+  unit: TimeSeriesUnit
+  /** False when there is not one finite value to plot. */
+  hasData: boolean
+  /** Every timestamp in the chart, ascending. */
+  times: number[]
+  /** Smallest and largest plotted value (both 0 when there is no data). */
+  min: number
+  max: number
+}
+
+/** Row key holding series `i`'s value: number, null (gap) or absent. */
+export function valueKey(seriesIndex: number): string {
+  return `v${seriesIndex}`
+}
+
+export function buildChartModel(
+  series: TimeSeries[],
+  mode: TimeSeriesMode,
+  unit: TimeSeriesUnit,
+): ChartModel {
+  const rowsByTime = new Map<number, ChartRow>()
+  const rowAt = (t: number): ChartRow => {
+    let row = rowsByTime.get(t)
+    if (!row) {
+      row = { t }
+      rowsByTime.set(t, row)
+    }
+    return row
+  }
+
+  const segments: ChartSegment[] = []
+  let hasData = false
+  let min = Infinity
+  let max = -Infinity
+
+  series.forEach((s, i) => {
+    const normalized = normalizePoints(s.points)
+    const points = mode === 'drawdown' ? toDrawdown(normalized, unit) : normalized
+
+    let segIndex = 0
+    let segLength = 0
+    const closeSegment = () => {
+      if (segLength === 0) return
+      segments.push({ dataKey: `s${i}_${segIndex}`, seriesIndex: i, single: segLength === 1 })
+      segIndex += 1
+      segLength = 0
+    }
+
+    for (const p of points) {
+      const row = rowAt(p.t)
+      row[valueKey(i)] = p.v
+      if (p.v === null) {
+        closeSegment()
+        continue
+      }
+      row[`s${i}_${segIndex}`] = p.v
+      segLength += 1
+      hasData = true
+      if (p.v < min) min = p.v
+      if (p.v > max) max = p.v
+    }
+    closeSegment()
+  })
+
+  const rows = [...rowsByTime.values()].sort((a, b) => a.t - b.t)
+  return {
+    rows,
+    segments,
+    names: series.map((s) => s.name),
+    unit: mode === 'drawdown' ? '%' : unit,
+    hasData,
+    times: rows.map((r) => r.t),
+    min: hasData ? min : 0,
+    max: hasData ? max : 0,
+  }
+}

package/src/components/history/__tests__/use-conditional-save.test.tsx

@@ -385,3 +385,63 @@ describe('resolving is a deliberate act', () => {
     expect(result.current.version).toBe(2);
   });
 });
+
+describe('a resolution cannot be raced', () => {
+  // The dialog disables these while busy, but the HOOK is exported on its own
+  // and a consumer wires its own controls (bd startsim-j19hf does exactly that).
+  it('ignores acceptTheirs mid-keepMine so the two cannot interleave', async () => {
+    let release: (v: ConditionalWriteOutcome) => void = () => {};
+    const second = new Promise<ConditionalWriteOutcome>((r) => {
+      release = r;
+    });
+    let call = 0;
+    const write = jest.fn(async () => {
+      call += 1;
+      return call === 1 ? REFUSAL : second;
+    });
+    const { result } = renderHook(() => useConditionalSave({ client: { write }, version: 2 }));
+
+    await act(async () => {
+      await result.current.save({ data: { blog: 'mine' } });
+    });
+
+    let inflight!: Promise<unknown>;
+    act(() => {
+      inflight = result.current.keepMine();
+    });
+    expect(result.current.resolving).toBe(true);
+
+    // The user hits "discard mine" while the overwrite is still in the air.
+    act(() => result.current.acceptTheirs());
+    // IGNORED, so the two never interleave: the conflict is still the one
+    // keepMine is resolving, not a half-cleared state.
+    expect(result.current.conflict?.currentVersion).toBe(3);
+    expect(result.current.version).toBe(2);
+
+    await act(async () => {
+      release({ status: 412, body: { detail: 'again', current_version: 9 } });
+      await inflight;
+    });
+
+    // One writer decided the outcome — keepMine's — rather than two racing.
+    expect(result.current.conflict?.currentVersion).toBe(9);
+    expect(result.current.conflict?.refusedBody).toEqual({ data: { blog: 'mine' } });
+    expect(result.current.paused).toBe(true);
+    expect(result.current.version).toBe(2);
+  });
+
+  it('does not fire two overwrites on a double click', async () => {
+    const { client, sent } = writer([REFUSAL, { status: 200, body: { version: 4 } }]);
+    const { result } = renderHook(() => useConditionalSave({ client, version: 2 }));
+
+    await act(async () => {
+      await result.current.save({ data: { blog: 'mine' } });
+    });
+    await act(async () => {
+      await Promise.all([result.current.keepMine(), result.current.keepMine()]);
+    });
+
+    // One refused save + exactly one overwrite.
+    expect(sent).toHaveLength(2);
+  });
+});

package/src/components/history/useConditionalSave.ts

@@ -171,6 +171,9 @@ export function useConditionalSave({
   const [conflict, setConflict] = useState<StaleSaveConflict | null>(null);
   const [dismissed, setDismissed] = useState(false);
   const [resolving, setResolving] = useState(false);
+  /** The synchronous twin of {@link resolving}. State lands a render too late to
+   *  stop a second click; this does not. */
+  const resolvingRef = useRef(false);
   const [lastError, setLastError] = useState<unknown>(null);
 
   // Read inside `save` so a stale closure cannot send a version the hook has
@@ -301,6 +304,13 @@ export function useConditionalSave({
   const keepMine = useCallback(async (): Promise<ConditionalSaveResult> => {
     const current = conflictRef.current;
     if (!current) return { status: 'paused' };
+    // RE-ENTRANCY IS GUARDED ON A REF, NOT ON `resolving`, AND THAT IS THE WHOLE
+    // POINT. `setResolving(true)` only reaches the DOM after a re-render, so a
+    // double click on "Save mine" lands both handlers before the button is
+    // disabled — and sends the overwrite TWICE. Measured, not theorised: the
+    // test below counted three writes where two were correct.
+    if (resolvingRef.current) return { status: 'paused' };
+    resolvingRef.current = true;
     // Adopting `current_version` is legitimate HERE and nowhere else: a person
     // has been told what changed and has chosen to replace it.
     const target = isVersion(current.currentVersion) ? current.currentVersion : undefined;
@@ -311,11 +321,17 @@ export function useConditionalSave({
     try {
       return await attempt(current.refusedBody, target);
     } finally {
+      resolvingRef.current = false;
       if (alive.current) setResolving(false);
     }
   }, [attempt]);
 
   const acceptTheirs = useCallback(() => {
+    // IGNORED MID-OVERWRITE, same posture as `save`. Discarding while a
+    // `keepMine` is in the air lets the two interleave, and the refusal of a
+    // save the reviewer has ALREADY ABANDONED then raises a fresh dialog about
+    // it — a conflict about text that no longer exists anywhere.
+    if (resolvingRef.current) return;
     const current = conflictRef.current;
     setVersionState(isVersion(current?.currentVersion) ? current!.currentVersion : undefined);
     setConflict(null);