diff --git a/apps/agent-forge/src/ui/MetricCard.tsx b/apps/agent-forge/src/ui/MetricCard.tsx
new file mode 100644
index 000000000..08b58ab9a
--- /dev/null
+++ b/apps/agent-forge/src/ui/MetricCard.tsx
@@ -0,0 +1,114 @@
+import type { ReactNode } from 'react';
+import { ArrowDown, ArrowUp, Minus } from 'lucide-react';
+import { Skeleton } from './Skeleton';
+import './metricCard.css';
+
+/** A change against a comparison window, shown under the value. */
+interface MetricDelta {
+ /** Signed change: positive is up, negative down, 0 no change. */
+ value: number;
+ /** Formats the magnitude (`Math.abs(value)`); the arrow and phrase carry the direction. Default `12%`. */
+ format?: (v: number) => string;
+ /** Which direction is good news (default `'up'`; `'down'` for errors, latency, cost). */
+ goodWhen?: 'up' | 'down';
+ /** The comparison, read after the change (default `'vs previous window'`). */
+ label?: string;
+}
+
+/** Props for {@link MetricCard}. */
+interface MetricCardProps {
+ /** Overline label ("Runs", "p95 latency"). */
+ label: string;
+ /** The metric, already formatted. */
+ value: ReactNode;
+ delta?: MetricDelta;
+ /** Recent values, oldest first, drawn as a tiny line; fewer than two points draw nothing. */
+ sparkline?: number[];
+ /** Muted line under the value ("last 24 h"). */
+ hint?: ReactNode;
+ /** Skeletons in place of the value, delta and sparkline. */
+ loading?: boolean;
+}
+
+const percent = (v: number) => `${v.toLocaleString('en-US', { maximumFractionDigits: 1 })}%`;
+
+/** good = success, bad = danger, neutral = muted (no change). */
+function toneOf(value: number, goodWhen: 'up' | 'down'): 'good' | 'bad' | 'neutral' {
+ if (value === 0) return 'neutral';
+ return value > 0 === (goodWhen === 'up') ? 'good' : 'bad';
+}
+
+function Delta({ value, format = percent, goodWhen = 'up', label = 'vs previous window' }: MetricDelta) {
+ const shown = format(Math.abs(value));
+ const Icon = value > 0 ? ArrowUp : value < 0 ? ArrowDown : Minus;
+ const spoken = value === 0 ? `no change ${label}` : `${value > 0 ? 'up' : 'down'} ${shown} ${label}`;
+ return (
+
+ {shown}
+ {spoken}
+
+ );
+}
+
+const SPARK_W = 96;
+const SPARK_H = 32;
+
+/** `points` for an SVG polyline spanning SPARK_W x SPARK_H (a flat series sits mid-height). */
+function sparkPoints(values: number[]): string {
+ const min = Math.min(...values);
+ const span = Math.max(...values) - min;
+ const step = SPARK_W / (values.length - 1);
+ return values
+ .map((v, i) => {
+ const y = span === 0 ? SPARK_H / 2 : SPARK_H - 2 - ((v - min) / span) * (SPARK_H - 4);
+ return `${(i * step).toFixed(1)},${y.toFixed(1)}`;
+ })
+ .join(' ');
+}
+
+function Sparkline({ values }: { values: number[] }) {
+ return (
+
+
+ );
+}
+
+/** One KPI tile: overline label, a 24px tabular value, optional delta, hint and sparkline. */
+export function MetricCard({ label, value, delta, sparkline, hint, loading }: MetricCardProps) {
+ // A NaN/Infinity change (0/0 against an empty window) shows no delta; non-finite points are dropped.
+ const showDelta = delta !== undefined && Number.isFinite(delta.value) && !loading;
+ const points = sparkline?.filter(Number.isFinite);
+ return (
+
+
+ {label}
+
+ {loading ? (
+ <>
+ Loading
+
+ {(showDelta || hint != null) && (
+
+ {showDelta && {hint} }
+
+ )}
+
+ {points && points.length >= 2 && !loading &&
}
+ {sparkline && loading &&
}
+
+ );
+}
diff --git a/apps/agent-forge/src/ui/Skeleton.tsx b/apps/agent-forge/src/ui/Skeleton.tsx
new file mode 100644
index 000000000..9b9021d10
--- /dev/null
+++ b/apps/agent-forge/src/ui/Skeleton.tsx
@@ -0,0 +1,88 @@
+import type { CSSProperties } from 'react';
+import './skeleton.css';
+
+/** A length: a number is pixels, a string is any CSS length (`'60%'`, `'1.5em'`). */
+type Length = number | string;
+
+const css = (v: Length | undefined) => (typeof v === 'number' ? `${v}px` : v);
+
+/** Props for {@link Skeleton}. */
+interface SkeletonProps {
+ width?: Length;
+ height?: Length;
+ /** Corner radius; defaults to `var(--radius-sm)`. */
+ radius?: string;
+ className?: string;
+}
+
+/**
+ * One shimmer block standing in for content that is still loading. Purely
+ * decorative (`aria-hidden`): a screen that shows only skeletons pairs them
+ * with {@link SkeletonRows} or its own status text.
+ */
+export function Skeleton({ width, height, radius = 'var(--radius-sm)', className }: SkeletonProps) {
+ const style: CSSProperties = { width: css(width), height: css(height), borderRadius: radius };
+ return
;
+}
+
+/** Cell widths cycled down the rows, so a block reads as ragged text rather than bars. */
+const WIDTHS = ['72%', '56%', '84%', '48%', '64%', '78%'];
+const widthAt = (row: number, col: number) => WIDTHS[(row * 2 + col) % WIDTHS.length];
+
+/** Props for {@link SkeletonRows}. */
+interface SkeletonRowsProps {
+ /** Number of rows (default 6). */
+ rows?: number;
+ /** Blocks per row (default 1). */
+ cols?: number;
+ /** `'tr'` renders table rows of `
`s for a ` `; `'div'` (default) a stack of flex rows. */
+ as?: 'div' | 'tr';
+ /** Extra class for the cell at column `index` (table alignment, e.g. `'dt-right'`). */
+ cellClassName?: (index: number) => string | undefined;
+}
+
+const Status = () => (
+
+ Loading
+
+);
+
+/** Table rows: the status sits in the first cell; the other rows are hidden from assistive tech. */
+function TableRows({ rows, cols, cellClassName }: Required>) {
+ return (
+ <>
+ {Array.from({ length: rows }, (_, r) => (
+ 0 ? true : undefined}>
+ {Array.from({ length: cols }, (_, c) => (
+
+ {r === 0 && c === 0 &&
+ ))}
+
+ ))}
+
+ );
+}
+
+/**
+ * A block of shimmer rows with ONE visually-hidden `role="status"` "Loading"
+ * text: the loading state for tables and lists. Static under reduced motion.
+ */
+export function SkeletonRows({ rows = 6, cols = 1, as = 'div', cellClassName = () => undefined }: SkeletonRowsProps) {
+ if (as === 'tr') return
+
+ {Array.from({ length: rows }, (_, r) => (
+
+ {Array.from({ length: cols }, (_, c) => (
+
+
+ ))}
+
+ ))}
+
- {PRESETS.map((p) => (
+
+ {PRESETS.map((p) => (
+ {
+ setCustomOpen(false);
+ onChange({ preset: p });
+ }}
+ >
+ {p}
+
+ ))}
{
- setCustomOpen(false);
- onChange({ preset: p });
- }}
+ aria-pressed={absolute}
+ aria-expanded={customOpen}
+ onClick={() => setCustomOpen((o) => !o)}
>
- {p}
+
- ))}
- setCustomOpen((o) => !o)}
- >
- Custom
-
+
{customOpen && (
From
-
To
-
onChange({ from: fromMs, to: toMs })}
>
diff --git a/apps/agent-forge/src/ui/__tests__/Card.test.tsx b/apps/agent-forge/src/ui/__tests__/Card.test.tsx
new file mode 100644
index 000000000..af9ef4ce3
--- /dev/null
+++ b/apps/agent-forge/src/ui/__tests__/Card.test.tsx
@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+
+import { Card } from '../Card';
+import { render } from './render';
+
+describe('Card', () => {
+ it('renders a section whose header title labels it, with description and actions', () => {
+ const c = render(
+ Refresh }>
+
body
+ ,
+ );
+ const card = c.querySelector('section.card') as HTMLElement;
+ const title = card.querySelector('.card-header h2.card-title') as HTMLElement;
+ expect(title.textContent).toBe('Fleet');
+ expect(title.id).not.toBe('');
+ expect(card.getAttribute('aria-labelledby')).toBe(title.id);
+ expect(card.querySelector('.card-description')?.textContent).toBe('Agents seen in the window');
+ expect(card.querySelector('.card-actions button')?.textContent).toBe('Refresh');
+ expect(card.querySelector('.card-body p')?.textContent).toBe('body');
+ expect(card.classList.contains('card-pad-md')).toBe(true);
+ });
+
+ it('renders no header without a title, and no aria-labelledby', () => {
+ const c = render(
+
+
+ ,
+ );
+ const card = c.querySelector('div.card') as HTMLElement;
+ expect(card.querySelector('.card-header')).toBeNull();
+ expect(card.hasAttribute('aria-labelledby')).toBe(false);
+ expect(card.classList.contains('card-pad-none')).toBe(true);
+ expect(card.classList.contains('extra')).toBe(true);
+ });
+
+ it('a titled div card keeps its header but is not labelled by it', () => {
+ const c = render(
+
+ x
+ ,
+ );
+ const card = c.querySelector('div.card') as HTMLElement;
+ expect(card.querySelector('.card-title')?.textContent).toBe('Plain');
+ expect(card.hasAttribute('aria-labelledby')).toBe(false);
+ });
+});
diff --git a/apps/agent-forge/src/ui/__tests__/DataTable.test.tsx b/apps/agent-forge/src/ui/__tests__/DataTable.test.tsx
index a863782a7..80b34fb35 100644
--- a/apps/agent-forge/src/ui/__tests__/DataTable.test.tsx
+++ b/apps/agent-forge/src/ui/__tests__/DataTable.test.tsx
@@ -3,7 +3,7 @@ import { resolve } from 'node:path';
import { act } from 'react';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { DataTable, type Column, type TableSort } from '../DataTable';
+import { DataTable, ErrorCell, type Column, type TableSort } from '../DataTable';
import { render, rerender } from './render';
interface Row {
@@ -115,6 +115,36 @@ describe('DataTable rendering', () => {
expect(c.textContent).not.toContain('Nothing here');
});
+ it('shows six skeleton rows (one cell per visible column) and one Loading status on a first load', () => {
+ setWidth(1200);
+ const c = render(
r.id} loading empty="Nothing here" />);
+ const skeletonRows = c.querySelectorAll('tbody tr.skeleton-row');
+ expect(skeletonRows).toHaveLength(6);
+ expect(skeletonRows[0].querySelectorAll('td')).toHaveLength(3);
+ expect(skeletonRows[0].querySelectorAll('td')[1].classList.contains('dt-right')).toBe(true);
+ expect(c.querySelectorAll('tbody [role="status"]')).toHaveLength(1);
+ expect(c.querySelector('tbody [role="status"]')?.textContent).toBe('Loading');
+ expect(c.textContent).not.toContain('Loading…');
+ // Skeleton rows are not data rows: no row index, never focusable.
+ expect(c.querySelector('tbody tr[data-row-index]')).toBeNull();
+ setWidth(600);
+ expect(c.querySelectorAll('tbody tr.skeleton-row')[0].querySelectorAll('td')).toHaveLength(2);
+ });
+
+ it('keeps real rows (no skeleton) when loading with rows already shown', () => {
+ const c = render( r.id} loading empty="x" />);
+ expect(c.querySelector('.skeleton-row')).toBeNull();
+ });
+
+ it('titles plain-text cells so truncated text keeps a tooltip', () => {
+ setWidth(1200);
+ const c = render( r.id} empty="x" />);
+ const [name, tokens, id] = bodyRows(c)[0].querySelectorAll('td');
+ expect(name.title).toBe('alpha');
+ expect(tokens.title).toBe('10 tok');
+ expect(id.title).toBe('a');
+ });
+
it('applies the density class (compact default, comfortable on request)', () => {
const c = render( r.id} empty="x" />);
expect(c.querySelector('table')?.classList.contains('dt-compact')).toBe(true);
@@ -395,3 +425,81 @@ describe('DataTable paging', () => {
expect(btn('Previous').disabled).toBe(false);
});
});
+
+describe('ErrorCell', () => {
+ it('renders danger text with an aria-hidden 14px alert icon and a title tooltip', () => {
+ const c = render(upstream 529 overloaded );
+ const cell = c.querySelector('.dt-error') as HTMLElement;
+ expect(cell.textContent).toBe('upstream 529 overloaded');
+ expect(cell.title).toBe('upstream 529 overloaded');
+ const svg = cell.querySelector('svg') as SVGElement;
+ expect(svg.getAttribute('aria-hidden')).toBe('true');
+ expect(svg.getAttribute('width')).toBe('14');
+ expect(cell.querySelector('.dt-error-text')?.textContent).toBe('upstream 529 overloaded');
+ });
+
+ it('takes an explicit title for non-string content', () => {
+ const c = render(
+
+ boom
+ ,
+ );
+ expect((c.querySelector('.dt-error') as HTMLElement).title).toBe('boom: stack');
+ });
+});
+
+describe('DataTable layout (review fixes)', () => {
+ const css = (f: string) => readFileSync(resolve(__dirname, '..', f), 'utf8');
+ const rule = (src: string, sel: string) => src.match(new RegExp(`(^|\\n)${sel.replace(/[.[\]()*]/g, '\\$&')}\\s*\\{([^}]*)\\}`))?.[2] ?? '';
+
+ it('the wrap clips instead of scrolling, so the sticky header sticks to the screen', () => {
+ const table = css('dataTable.css');
+ expect(rule(table, '.data-table-wrap')).toMatch(/overflow-x:\s*clip/);
+ expect(rule(table, '.data-table-wrap')).toMatch(/min-height:\s*min-content/);
+ expect(rule(table, '.data-table-wrap.dt-scroll-x')).toMatch(/overflow-x:\s*auto/);
+ expect(rule(css('card.css'), '.card-pad-none > .card-body')).toMatch(/overflow:\s*clip/);
+ });
+
+ it('becomes a horizontal scroller (dt-scroll-x) only while the table is wider than the wrap', () => {
+ const offset = vi.spyOn(HTMLElement.prototype, 'offsetWidth', 'get').mockReturnValue(800);
+ const client = vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockReturnValue(800);
+ const c = render( r.id} empty="x" />);
+ const wrap = () => c.querySelector('.data-table-wrap') as HTMLElement;
+ expect(wrap().classList.contains('dt-scroll-x')).toBe(false);
+ offset.mockReturnValue(1200);
+ rerender( r.id} empty="y" />);
+ expect(wrap().classList.contains('dt-scroll-x')).toBe(true);
+ offset.mockReturnValue(800);
+ rerender( r.id} empty="z" />);
+ expect(wrap().classList.contains('dt-scroll-x')).toBe(false);
+ client.mockRestore();
+ });
+
+ it('maxHeight opts into a bounded scroller (both axes) whose header sticks inside it', () => {
+ const c = render( r.id} maxHeight={480} empty="x" />);
+ const wrap = c.querySelector('.data-table-wrap') as HTMLElement;
+ expect(wrap.classList.contains('dt-scroll')).toBe(true);
+ expect(wrap.style.maxHeight).toBe('480px');
+ rerender( r.id} maxHeight="calc(100dvh - 200px)" empty="x" />);
+ expect(wrap.style.maxHeight).toBe('calc(100dvh - 200px)');
+ expect(rule(css('dataTable.css'), '.data-table-wrap.dt-scroll')).toMatch(/overflow:\s*auto/);
+ rerender( r.id} empty="x" />);
+ expect(wrap.classList.contains('dt-scroll')).toBe(false);
+ expect(wrap.style.maxHeight).toBe('');
+ });
+
+ it('wraps header labels in .dt-label so they ellipsise inside the flex row', () => {
+ setWidth(1200);
+ const c = render( r.id} empty="x" />);
+ expect([...c.querySelectorAll('th .dt-label')].map((s) => s.textContent)).toEqual(['Name', 'Tokens', 'Id']);
+ expect(rule(css('dataTable.css'), '.dt-label')).toMatch(/text-overflow:\s*ellipsis/);
+ });
+
+ it('pager has no side padding outside an edge-to-edge card; compact buttons only in .dt-actions', () => {
+ const table = css('dataTable.css');
+ expect(rule(table, '.dt-pager')).toMatch(/padding:\s*var\(--space-2\)\s+0;/);
+ expect(rule(css('card.css'), '.card-pad-none .dt-pager')).toMatch(/padding-inline/);
+ expect(table).not.toMatch(/\.data-table td \.btn/);
+ expect(rule(table, '.dt-actions .btn')).toMatch(/min-height:\s*26px/);
+ });
+});
diff --git a/apps/agent-forge/src/ui/__tests__/FilterBar.test.tsx b/apps/agent-forge/src/ui/__tests__/FilterBar.test.tsx
index 0d26e4359..af5cdf738 100644
--- a/apps/agent-forge/src/ui/__tests__/FilterBar.test.tsx
+++ b/apps/agent-forge/src/ui/__tests__/FilterBar.test.tsx
@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
import { act } from 'react';
import { afterEach, describe, expect, it, vi } from 'vitest';
@@ -181,6 +183,39 @@ describe('TimeRangePicker via FilterBar', () => {
});
});
+describe('FilterBar look', () => {
+ it('presets and Custom sit in one segmented control; the group keeps its name', () => {
+ render(
+
+ (i === 2 ? 'dt-right' : undefined)} />
+
+
,
+ );
+ const trs = c.querySelectorAll('tbody tr.skeleton-row');
+ expect(trs).toHaveLength(2);
+ expect(trs[0].querySelectorAll('td')).toHaveLength(3);
+ expect(trs[0].querySelectorAll('td')[2].classList.contains('dt-right')).toBe(true);
+ expect(c.querySelectorAll('[role="status"]')).toHaveLength(1);
+ expect(trs[0].querySelector('[role="status"]')?.textContent).toBe('Loading');
+ expect(trs[1].getAttribute('aria-hidden')).toBe('true');
+ });
+});
diff --git a/apps/agent-forge/src/ui/__tests__/primitives.test.tsx b/apps/agent-forge/src/ui/__tests__/primitives.test.tsx
index 57cea14c2..1a568b69c 100644
--- a/apps/agent-forge/src/ui/__tests__/primitives.test.tsx
+++ b/apps/agent-forge/src/ui/__tests__/primitives.test.tsx
@@ -1,4 +1,5 @@
import { act } from 'react';
+import { Search } from 'lucide-react';
import { afterEach, describe, expect, it, vi } from 'vitest';
import { render as mount } from './render';
@@ -97,12 +98,28 @@ describe('StatusPill', () => {
describe('EmptyState', () => {
it('renders the title, hint, action and a decorative icon', () => {
- render(Run} icon={Run} icon={Search} />);
const root = container.querySelector('.empty-state') as HTMLElement;
expect(root.querySelector('.empty-state-title')?.textContent).toBe('No traces yet');
expect(root.querySelector('.empty-state-hint')?.textContent).toBe('Run an agent.');
expect(root.querySelector('.empty-state-action button')?.textContent).toBe('Run');
expect(root.querySelector('.empty-state-icon')?.getAttribute('aria-hidden')).toBe('true');
+ const svg = root.querySelector('.empty-state-icon svg') as SVGElement;
+ expect(svg.classList.contains('lucide-search')).toBe(true);
+ expect(svg.getAttribute('width')).toBe('20');
+ expect(svg.getAttribute('stroke-width')).toBe('1.75');
+ });
+
+ it('defaults to the Inbox icon tile, and icon={null} renders no tile', () => {
+ render(
+ <>
+