@tangle-network/ui 11.41.0 → 11.42.0

package/dist/primitives.js

@@ -56,6 +56,9 @@ import { HoverCard, HoverCardContent, HoverCardDescription, HoverCardHeader, Hov
 import { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "./primitives/breadcrumb.js";
 import { IconTile, initialsOf } from "./primitives/icon-tile.js";
 import { Metric, MetricStrip } from "./primitives/metric-strip.js";
+import { normalizeSeries, periodDelta, seriesAreaPath, seriesExtent, seriesLinePath, seriesMean, seriesScale } from "./lib/series.js";
+import { SeriesSparkline } from "./primitives/series-sparkline.js";
+import { MetricChart } from "./primitives/metric-chart.js";
 import { FilterField, Toolbar } from "./primitives/toolbar.js";
 import { Logo, TangleKnot } from "@tangle-network/brand";
-export { Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, ArtifactPane, Avatar, AvatarFallback, AvatarImage, Badge, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, CATEGORY_TONES, Calendar, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, Chip, CodeBlock, Collapsible, CollapsibleContent, CollapsibleTrigger, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, DatePicker, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropZone, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, Field, FilterField, Heading, HelpText, HoverCard, HoverCardContent, HoverCardDescription, HoverCardHeader, HoverCardTitle, HoverCardTrigger, IconTile, InlineCode, Input, Label, Logo, Metric, MetricStrip, PageHeader, PageShell, Pagination, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, RadioGroup, RadioGroupItem, SegmentedControl, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, SettingsList, SettingsListItem, SettingsRow, SettingsSection, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, StatusPill, Switch, TONE_CLASSES, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, TangleKnot, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, Textarea, ThemeToggle, TimeSelect, ToastContainer, ToastProvider, Toolbar, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UploadProgress, Wizard, WizardStep, badgeVariants, buttonVariants, fieldMessageId, formatCalendarDate, initialsOf, localToday, parseCalendarDate, toneFor, useTheme, useToast };
+export { Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, ArtifactPane, Avatar, AvatarFallback, AvatarImage, Badge, Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator, Button, CATEGORY_TONES, Calendar, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, Chip, CodeBlock, Collapsible, CollapsibleContent, CollapsibleTrigger, ContextMenu, ContextMenuCheckboxItem, ContextMenuContent, ContextMenuGroup, ContextMenuItem, ContextMenuLabel, ContextMenuPortal, ContextMenuRadioGroup, ContextMenuRadioItem, ContextMenuSeparator, ContextMenuShortcut, ContextMenuSub, ContextMenuSubContent, ContextMenuSubTrigger, ContextMenuTrigger, CopyButton, DatePicker, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropZone, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, Field, FilterField, Heading, HelpText, HoverCard, HoverCardContent, HoverCardDescription, HoverCardHeader, HoverCardTitle, HoverCardTrigger, IconTile, InlineCode, Input, Label, Logo, Metric, MetricChart, MetricStrip, PageHeader, PageShell, Pagination, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, Progress, RadioGroup, RadioGroupItem, SegmentedControl, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, SeriesSparkline, SettingsList, SettingsListItem, SettingsRow, SettingsSection, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, SidebarDropZone, Skeleton, SkeletonCard, SkeletonTable, Slider, StatCard, StatusPill, Switch, TONE_CLASSES, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, Tag, TangleKnot, TerminalCursor, TerminalDisplay, TerminalInput, TerminalLine, TextShimmer, Textarea, ThemeToggle, TimeSelect, ToastContainer, ToastProvider, Toolbar, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, UploadProgress, Wizard, WizardStep, badgeVariants, buttonVariants, fieldMessageId, formatCalendarDate, initialsOf, localToday, normalizeSeries, parseCalendarDate, periodDelta, seriesAreaPath, seriesExtent, seriesLinePath, seriesMean, seriesScale, toneFor, useTheme, useToast };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/ui",
-  "version": "11.41.0",
+  "version": "11.42.0",
   "description": "Generic React UI components for Tangle products — primitives, chat, run, files, editor, markdown.",
   "type": "module",
   "license": "MIT",

package/src/lib/series.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it } from "vitest";
+import {
+  normalizeSeries,
+  periodDelta,
+  seriesAreaPath,
+  seriesExtent,
+  seriesLinePath,
+  seriesMean,
+  seriesScale,
+  type SeriesPoint,
+} from "./series";
+
+const DAY = 86_400_000;
+
+describe("normalizeSeries", () => {
+  it("parses epoch, ISO and Date times, drops non-finite readings and sorts", () => {
+    const points = normalizeSeries([
+      { at: "2026-10-21T07:00:00.000Z", value: 63 },
+      { at: 1_000, value: 61 },
+      { at: new Date("2026-10-20T07:00:00.000Z"), value: 62, value2: 40 },
+      { at: "not a date", value: 99 },
+      { at: 2_000, value: Number.NaN },
+      { at: 3_000, value: 65, value2: Number.POSITIVE_INFINITY },
+    ]);
+    expect(points.map((point) => point.value)).toEqual([61, 65, 62, 63]);
+    expect(points[0]!.at).toBe(1_000);
+    // A non-finite second reading drops value2, not the point.
+    expect(points[1]!.value2).toBeUndefined();
+    expect(points[2]!.value2).toBe(40);
+    for (let i = 1; i < points.length; i += 1) {
+      expect(points[i]!.at).toBeGreaterThanOrEqual(points[i - 1]!.at);
+    }
+  });
+
+  it("returns an empty series for empty input", () => {
+    expect(normalizeSeries([])).toEqual([]);
+  });
+});
+
+describe("seriesExtent", () => {
+  const points: SeriesPoint[] = [
+    { at: 10 * DAY, value: 60 },
+    { at: 20 * DAY, value: 80 },
+    { at: 30 * DAY, value: 70, value2: 45 },
+  ];
+
+  it("spans both readings with twelve percent padding by default", () => {
+    const extent = seriesExtent(points);
+    const span = 80 - 45;
+    expect(extent.lo).toBeCloseTo(45 - span * 0.12);
+    expect(extent.hi).toBeCloseTo(80 + span * 0.12);
+    expect(extent.tLo).toBe(10 * DAY);
+    expect(extent.tHi).toBe(30 * DAY);
+  });
+
+  it("widens the domain to cover included reference values", () => {
+    const extent = seriesExtent(points, { include: [95, 30] });
+    expect(extent.hi).toBeGreaterThanOrEqual(95);
+    expect(extent.lo).toBeLessThanOrEqual(30);
+  });
+
+  it("honours an explicit padding of zero", () => {
+    const extent = seriesExtent(points, { padding: 0 });
+    expect(extent.lo).toBe(45);
+    expect(extent.hi).toBe(80);
+  });
+
+  it("opens up a degenerate value span so a flat series still centres", () => {
+    const extent = seriesExtent([
+      { at: DAY, value: 50 },
+      { at: 2 * DAY, value: 50 },
+    ]);
+    expect(extent.lo).toBeLessThan(50);
+    expect(extent.hi).toBeGreaterThan(50);
+  });
+
+  it("opens up a degenerate time span for a single reading", () => {
+    const extent = seriesExtent([{ at: DAY, value: 50 }]);
+    expect(extent.tHi - extent.tLo).toBe(24 * 3_600_000);
+    expect((extent.tLo + extent.tHi) / 2).toBe(DAY);
+  });
+
+  it("returns a usable default extent for an empty series", () => {
+    const extent = seriesExtent([]);
+    expect(extent.lo).toBeLessThan(extent.hi);
+    expect(extent.tLo).toBeLessThan(extent.tHi);
+  });
+});
+
+describe("seriesScale", () => {
+  it("maps extent corners to the padded box corners", () => {
+    const extent = { lo: 0, hi: 10, tLo: 0, tHi: 100 };
+    const scale = seriesScale(extent, 200, 100, 10);
+    expect(scale.x(0)).toBe(10);
+    expect(scale.x(100)).toBe(190);
+    expect(scale.y(0)).toBe(90);
+    expect(scale.y(10)).toBe(10);
+    expect(scale.x(50)).toBeCloseTo(100);
+    expect(scale.y(5)).toBeCloseTo(50);
+  });
+});
+
+describe("seriesMean", () => {
+  it("averages finite values and ignores non-finite ones", () => {
+    expect(seriesMean([2, 4, 6])).toBe(4);
+    expect(seriesMean([2, Number.NaN, 4])).toBe(3);
+  });
+
+  it("returns null when there is nothing to average", () => {
+    expect(seriesMean([])).toBeNull();
+  });
+});
+
+describe("periodDelta", () => {
+  const latest = 60 * DAY;
+  const points: SeriesPoint[] = [
+    { at: latest - 45 * DAY, value: 80 }, // prior window
+    { at: latest - 40 * DAY, value: 60 }, // prior window
+    { at: latest - 10 * DAY, value: 50 }, // recent window
+    { at: latest, value: 70 }, // recent window
+  ];
+
+  it("measures both windows back from the latest measurement, not the wall clock", () => {
+    const result = periodDelta(points, 30 * DAY)!;
+    expect(result.current).toBe(60);
+    expect(result.previous).toBe(70);
+    expect(result.delta).toBe(-10);
+  });
+
+  it("reports a null delta when the prior window has no data", () => {
+    const result = periodDelta(points.slice(2), 30 * DAY)!;
+    expect(result.current).toBe(60);
+    expect(result.previous).toBeNull();
+    expect(result.delta).toBeNull();
+  });
+
+  it("excludes readings exactly on the window boundary from the recent window", () => {
+    const boundary: SeriesPoint[] = [
+      { at: latest - 30 * DAY, value: 100 },
+      { at: latest, value: 50 },
+    ];
+    const result = periodDelta(boundary, 30 * DAY)!;
+    expect(result.current).toBe(50);
+    expect(result.previous).toBe(100);
+  });
+
+  it("returns null for an empty series", () => {
+    expect(periodDelta([], 30 * DAY)).toBeNull();
+  });
+});
+
+describe("seriesLinePath / seriesAreaPath", () => {
+  const placed = [
+    { x: 0, y: 10 },
+    { x: 5, y: 0 },
+    { x: 10, y: 10 },
+  ];
+
+  it("builds a move/line path", () => {
+    expect(seriesLinePath(placed)).toBe("M0.00,10.00 L5.00,0.00 L10.00,10.00");
+  });
+
+  it("closes the area path along the baseline", () => {
+    expect(seriesAreaPath(placed, 12)).toBe(
+      "M0.00,10.00 L5.00,0.00 L10.00,10.00L10.00,12L0.00,12Z",
+    );
+  });
+
+  it("draws no area for fewer than two points", () => {
+    expect(seriesAreaPath([{ x: 0, y: 0 }], 12)).toBe("");
+  });
+});

package/src/lib/series.ts

@@ -0,0 +1,174 @@
+/**
+ * src/lib/series.ts — pure time-series math shared by the chart primitives.
+ * No React, no DOM: unit-tested directly. All periods are relative to the
+ * LATEST measurement in the series, never to the wall clock, so a seeded
+ * demo or a backfilled import never goes stale.
+ */
+
+/** A point as callers supply it: `at` accepts epoch ms, ISO text or a Date. */
+export interface SeriesPointInput {
+  at: number | string | Date;
+  value: number;
+  /** Second reading for dual series (diastolic next to systolic). */
+  value2?: number;
+}
+
+/** A normalized point: finite numbers, epoch-ms time, ascending order. */
+export interface SeriesPoint {
+  at: number;
+  value: number;
+  value2?: number;
+}
+
+const asTime = (at: number | string | Date): number | null => {
+  const time =
+    at instanceof Date ? at.getTime() : typeof at === "number" ? at : Date.parse(at);
+  return Number.isFinite(time) ? time : null;
+};
+
+/** Drop non-finite readings and sort by measurement time. */
+export function normalizeSeries(
+  points: readonly SeriesPointInput[],
+): SeriesPoint[] {
+  const normalized: SeriesPoint[] = [];
+  for (const point of points) {
+    const at = asTime(point.at);
+    if (at === null || !Number.isFinite(point.value)) continue;
+    const { value2 } = point;
+    normalized.push(
+      value2 !== undefined && Number.isFinite(value2)
+        ? { at, value: point.value, value2 }
+        : { at, value: point.value },
+    );
+  }
+  return normalized.sort((a, b) => a.at - b.at);
+}
+
+export interface SeriesExtent {
+  /** Padded value domain. */
+  lo: number;
+  hi: number;
+  /** Time domain, never degenerate. */
+  tLo: number;
+  tHi: number;
+}
+
+const TWELVE_HOURS_MS = 12 * 3_600_000;
+
+/**
+ * Value and time extents across both readings of every point. The value
+ * domain is padded by `padding` (fraction of the span, default 0.12) and
+ * widened to cover `include`d values (reference lines). Degenerate spans
+ * open up so a flat or single-reading series still centres.
+ */
+export function seriesExtent(
+  points: readonly SeriesPoint[],
+  options: { padding?: number; include?: readonly number[] } = {},
+): SeriesExtent {
+  const values = [
+    ...points.flatMap((point) =>
+      point.value2 === undefined ? [point.value] : [point.value, point.value2]
+    ),
+    ...(options.include ?? []),
+  ];
+  let lo = values.length > 0 ? Math.min(...values) : 0;
+  let hi = values.length > 0 ? Math.max(...values) : 1;
+  if (lo === hi) {
+    lo -= 1;
+    hi += 1;
+  }
+  const pad = (hi - lo) * (options.padding ?? 0.12);
+  lo -= pad;
+  hi += pad;
+  let tLo = points.length > 0 ? points[0]!.at : 0;
+  let tHi = points.length > 0 ? points[points.length - 1]!.at : 1;
+  if (tLo === tHi) {
+    tLo -= TWELVE_HOURS_MS;
+    tHi += TWELVE_HOURS_MS;
+  }
+  return { lo, hi, tLo, tHi };
+}
+
+export interface SeriesScale {
+  x: (at: number) => number;
+  y: (value: number) => number;
+  extent: SeriesExtent;
+}
+
+/** Project an extent into a `width` × `height` box with `pad` inset. */
+export function seriesScale(
+  extent: SeriesExtent,
+  width: number,
+  height: number,
+  pad: number,
+): SeriesScale {
+  const { lo, hi, tLo, tHi } = extent;
+  return {
+    extent,
+    x: (at) => pad + ((at - tLo) / (tHi - tLo)) * (width - 2 * pad),
+    y: (value) => height - pad - ((value - lo) / (hi - lo)) * (height - 2 * pad),
+  };
+}
+
+export interface PeriodDelta {
+  /** Mean of the latest `windowMs` of data, ending at the last measurement. */
+  current: number;
+  /** Mean of the window before that, when such data exists. */
+  previous: number | null;
+  /** `current - previous`, or null without a populated prior window. */
+  delta: number | null;
+}
+
+/** Mean of finite values, or null when there is nothing to average. */
+export function seriesMean(values: readonly number[]): number | null {
+  const finite = values.filter((value) => Number.isFinite(value));
+  if (finite.length === 0) return null;
+  return finite.reduce((sum, value) => sum + value, 0) / finite.length;
+}
+
+/**
+ * Compare the latest `windowMs` of primary readings against the window
+ * before it. Both windows end at the LATEST measurement, never the wall
+ * clock. Returns null for an empty series.
+ */
+export function periodDelta(
+  points: readonly SeriesPoint[],
+  windowMs: number,
+): PeriodDelta | null {
+  if (points.length === 0) return null;
+  const latest = points[points.length - 1]!.at;
+  const recentStart = latest - windowMs;
+  const previousStart = latest - 2 * windowMs;
+  const recent = points
+    .filter((point) => point.at > recentStart)
+    .map((point) => point.value);
+  const previous = points
+    .filter((point) => point.at > previousStart && point.at <= recentStart)
+    .map((point) => point.value);
+  const current = seriesMean(recent)!;
+  const previousMean = seriesMean(previous);
+  return {
+    current,
+    previous: previousMean,
+    delta: previousMean !== null ? current - previousMean : null,
+  };
+}
+
+/** Polyline path data for already-projected points. */
+export function seriesLinePath(points: ReadonlyArray<{ x: number; y: number }>): string {
+  return points
+    .map(
+      (point, index) =>
+        `${index === 0 ? "M" : "L"}${point.x.toFixed(2)},${point.y.toFixed(2)}`,
+    )
+    .join(" ");
+}
+
+/** Closed area path down to `baseline`, empty for fewer than two points. */
+export function seriesAreaPath(
+  points: ReadonlyArray<{ x: number; y: number }>,
+  baseline: number,
+): string {
+  if (points.length < 2) return "";
+  return `${seriesLinePath(points)}L${points[points.length - 1]!.x.toFixed(2)},${baseline}L${points[0]!.x.toFixed(2)},${baseline}Z`;
+}

package/src/presentation.ts

@@ -116,6 +116,20 @@ export const metricLayouts = {
   6: "grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 max-sm:[&>div:not(:nth-child(2n+1))]:border-l sm:max-lg:[&>div:not(:nth-child(3n+1))]:border-l lg:[&>div:not(:nth-child(6n+1))]:border-l",
 } as const;
 
+/** Hand-rolled SVG charts: every stroke and fill is currentColor against a
+ * token class, so ink stays theme-aware with no hardcoded hues. Charts draw
+ * lines and text only; the grouping plane (border, surface) is caller-owned. */
+export const chartPresentation = {
+  sparkline: "h-9 w-full text-primary",
+  root: "h-auto w-full",
+  axis: "text-muted-foreground",
+  gridLine: "opacity-20",
+  referenceLine: "opacity-60",
+  primarySeries: "text-primary",
+  secondarySeries: "text-muted-foreground",
+  area: "opacity-10",
+} as const;
+
 export const dialogPresentation = {
   overlay: "fixed inset-0 z-50 bg-black/40",
   transition: surfaceMotion,

package/src/primitives/index.ts

@@ -248,5 +248,26 @@ export type { CategoryTone, Tone, ToneClasses } from "./tone";
 export { MetricStrip, Metric } from "./metric-strip";
 export type { MetricStripProps, MetricProps } from "./metric-strip";
 
+export { SeriesSparkline } from "./series-sparkline";
+export type { SeriesSparklineProps } from "./series-sparkline";
+export { MetricChart } from "./metric-chart";
+export type { ChartReferenceLine, MetricChartProps } from "./metric-chart";
+export {
+  normalizeSeries,
+  periodDelta,
+  seriesAreaPath,
+  seriesExtent,
+  seriesLinePath,
+  seriesMean,
+  seriesScale,
+} from "../lib/series";
+export type {
+  PeriodDelta,
+  SeriesExtent,
+  SeriesPoint,
+  SeriesPointInput,
+  SeriesScale,
+} from "../lib/series";
+
 export { Toolbar, FilterField } from "./toolbar";
 export type { ToolbarProps, FilterFieldProps } from "./toolbar";

package/src/primitives/metric-chart.stories.tsx

@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { MetricChart } from "./metric-chart";
+
+const meta = {
+  title: "Primitives/MetricChart",
+  component: MetricChart,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof MetricChart>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const DAY = 86_400_000;
+const t0 = Date.parse("2026-08-24T07:00:00.000Z");
+
+const bloodPressure = Array.from({ length: 12 }, (_, index) => ({
+  at: t0 + index * 5 * DAY,
+  value: 118 + ((index * 7) % 9),
+  value2: 74 + ((index * 5) % 8),
+}));
+
+const steps = Array.from({ length: 12 }, (_, index) => ({
+  at: t0 + index * 5 * DAY,
+  value: 6_200 + ((index * 1_937) % 4_800),
+}));
+
+export const DualSeries: Story = {
+  args: {
+    title: "Blood pressure",
+    unit: "mmHg",
+    decimals: 0,
+    points: bloodPressure,
+    referenceLines: [
+      { value: 120, label: "120 systolic" },
+      { value: 80, label: "80 diastolic", series: "secondary" },
+    ],
+  },
+};
+
+export const SingleSeries: Story = {
+  args: {
+    title: "Steps",
+    unit: "steps",
+    decimals: 0,
+    points: steps,
+  },
+};
+
+export const SingleReading: Story = {
+  args: {
+    title: "Weight",
+    unit: "kg",
+    decimals: 1,
+    points: [{ at: t0, value: 71.4 }],
+  },
+};

package/src/primitives/metric-chart.test.tsx

@@ -0,0 +1,118 @@
+import * as React from "react";
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { MetricChart } from "./metric-chart";
+
+afterEach(cleanup);
+
+const DAY = 86_400_000;
+const t0 = Date.parse("2026-09-01T07:00:00.000Z");
+const points = Array.from({ length: 10 }, (_, index) => ({
+  at: t0 + index * 5 * DAY,
+  value: 118 + (index % 3) * 4,
+  value2: 76 + (index % 2) * 4,
+}));
+
+describe("MetricChart", () => {
+  it("renders an accessible svg with a generated summary description", () => {
+    const { container } = render(
+      <MetricChart points={points} title="Blood pressure" unit="mmHg" decimals={0} />,
+    );
+    const svg = screen.getByRole("img", { name: "Blood pressure" });
+    expect(svg.querySelector("title")!.textContent).toBe("Blood pressure");
+    const desc = svg.querySelector("desc")!.textContent!;
+    expect(desc).toContain("10 readings");
+    expect(desc).toContain("min 118");
+    expect(desc).toContain("max 126");
+    expect(desc).toContain("mmHg");
+    // Primary line, area and dotted secondary series.
+    expect(container.querySelectorAll("path").length).toBeGreaterThanOrEqual(3);
+  });
+
+  it("honours a caller-provided description", () => {
+    const { container } = render(
+      <MetricChart points={points} title="Blood pressure" description="Custom summary." />,
+    );
+    expect(container.querySelector("desc")!.textContent).toBe("Custom summary.");
+  });
+
+  it("draws gridlines, date ticks and labelled reference lines on muted ink", () => {
+    const { container } = render(
+      <MetricChart
+        points={points}
+        title="Blood pressure"
+        referenceLines={[
+          { value: 120, label: "120 systolic" },
+          { value: 80, label: "80 diastolic", series: "secondary" },
+        ]}
+      />,
+    );
+    expect(screen.getByText("120 systolic")).toBeInTheDocument();
+    expect(screen.getByText("80 diastolic")).toBeInTheDocument();
+    // Four interior y ticks plus three x date ticks.
+    expect(screen.getByText("Sep 1")).toBeInTheDocument();
+    const dashed = Array.from(container.querySelectorAll("line")).filter(
+      (line) => line.getAttribute("stroke-dasharray") === "5 4",
+    );
+    expect(dashed).toHaveLength(2);
+    for (const line of dashed) expect(line.closest("g")!.getAttribute("class")).toContain("text-muted-foreground");
+  });
+
+  it("drops secondary reference lines when the series has no second reading", () => {
+    const single = points.map(({ at, value }) => ({ at, value }));
+    const { container } = render(
+      <MetricChart
+        points={single}
+        title="Heart rate"
+        referenceLines={[{ value: 80, label: "80 diastolic", series: "secondary" }]}
+      />,
+    );
+    expect(screen.queryByText("80 diastolic")).toBeNull();
+    expect(
+      Array.from(container.querySelectorAll("line")).filter(
+        (line) => line.getAttribute("stroke-dasharray") === "5 4",
+      ),
+    ).toHaveLength(0);
+  });
+
+  it("marks a single reading and renders axes only when data exists", () => {
+    const { container, rerender } = render(
+      <MetricChart points={[points[0]!]} title="Blood pressure" />,
+    );
+    expect(container.querySelectorAll("circle")).toHaveLength(1);
+    rerender(<MetricChart points={[]} title="Blood pressure" />);
+    expect(container.querySelectorAll("line")).toHaveLength(0);
+    expect(container.querySelectorAll("path")).toHaveLength(0);
+    expect(screen.getByRole("img", { name: "Blood pressure" })).toBeInTheDocument();
+  });
+
+  it("keeps every stroke and fill on currentColor", () => {
+    const { container } = render(<MetricChart points={points} title="Blood pressure" />);
+    for (const element of Array.from(container.querySelectorAll("[stroke], [fill]"))) {
+      const paint = element.getAttribute("stroke") ?? element.getAttribute("fill");
+      expect(["currentColor", "none"]).toContain(paint);
+    }
+  });
+
+  it("supports caller value and time formatting", () => {
+    render(
+      <MetricChart
+        points={points}
+        title="Blood pressure"
+        formatValue={(value) => `${value.toFixed(0)}!`}
+        formatTime={() => "sometime"}
+      />,
+    );
+    expect(screen.getAllByText("sometime")).toHaveLength(3);
+    expect(screen.getAllByText(/!$/).length).toBeGreaterThan(0);
+  });
+
+  it("preserves ref, caller attributes and caller classes", () => {
+    const ref = React.createRef<SVGSVGElement>();
+    const { container } = render(
+      <MetricChart ref={ref} points={points} title="Blood pressure" data-testid="bp" className="max-w-md" />,
+    );
+    expect(ref.current).toBe(container.querySelector("svg"));
+    expect(screen.getByTestId("bp").getAttribute("class")).toContain("max-w-md");
+  });
+});