feat: add StatTile trend indicator

Author: beihaiguaishou

README.md

@@ -92,6 +92,15 @@ normalization so duplicate pairs such as `usdc` and `USDC` cannot be registered.
 
 ## Accessibility
 
+### StatTile Trend Indicators
+
+`StatTile` accepts optional `delta?: number` and `trend?: "up" | "down" | "flat"`
+props for dashboards that need to show movement between polling intervals. A
+numeric `delta` automatically selects the trend direction; an explicit `trend`
+can be used when the caller already has direction metadata. The rendered badge
+uses direction text such as `Up +4`, `Down -2`, or `Flat 0` plus screen-reader
+copy, so color is never the only signal.
+
 ### ARIA Live Regions
 
 Dynamic list updates (loading → loaded / loading → empty) on the pairs, events, api-keys, and webhooks pages are wrapped in `aria-live="polite"` regions so screen-reader users are notified when content arrives. Error messages continue to use `role="alert"` for assertive announcements. A single polite region per page prevents double announcements.

src/app/quote/Client.tsx

@@ -2,6 +2,7 @@
 
 import { useState } from "react";
 import type { ApiError } from "@/lib/apiClient";
+import { assetsDiffer, isValidAmount } from "@/lib/quote";
 
 type Quote = {
   source_asset: string;
@@ -38,11 +39,19 @@ export default function QuoteClient() {
     setRequestId(null);
     setQuote(null);
 
-    if (!assetsDiffer(sourceAsset, destAsset)) {
+    const normalizedSourceAsset = normalizeAssetCode(sourceAsset);
+    const normalizedDestAsset = normalizeAssetCode(destAsset);
+    const normalizedAmount = amount.trim();
+
+    if (!normalizedSourceAsset || !normalizedDestAsset) {
+      setError("Asset codes must be 1-12 letters or numbers.");
+      return;
+    }
+    if (!assetsDiffer(normalizedSourceAsset, normalizedDestAsset)) {
       setError("Source and destination assets must differ.");
       return;
     }
-    if (!isValidAmount(amount)) {
+    if (!isValidAmount(normalizedAmount)) {
       setError("Amount must be a positive integer (base units).");
       return;
     }

src/components/StatTile.tsx

@@ -1,15 +1,58 @@
 import { type ReactNode } from "react";
+import { Badge } from "./Badge";
+
+type Trend = "up" | "down" | "flat";
 
 type Props = {
   label: ReactNode;
   value: ReactNode;
+  delta?: number;
+  trend?: Trend;
+};
+
+const trendFromDelta = (delta: number): Trend => {
+  if (delta > 0) return "up";
+  if (delta < 0) return "down";
+  return "flat";
+};
+
+const trendCopy: Record<Trend, { label: string; variant: "neutral" | "ok" | "danger" }> = {
+  up: { label: "Up", variant: "ok" },
+  down: { label: "Down", variant: "danger" },
+  flat: { label: "Flat", variant: "neutral" },
+};
+
+const signedDelta = (trend: Trend, delta: number): string => {
+  const magnitude = Math.abs(delta).toString();
+  if (trend === "up") return `+${magnitude}`;
+  if (trend === "down") return `-${magnitude}`;
+  return "0";
 };
 
-export function StatTile({ label, value }: Props) {
+export function StatTile({ label, value, delta, trend }: Props) {
+  const resolvedTrend = trend ?? (delta !== undefined ? trendFromDelta(delta) : undefined);
+  const trendMeta = resolvedTrend ? trendCopy[resolvedTrend] : undefined;
+  const visualDelta =
+    resolvedTrend && delta !== undefined ? signedDelta(resolvedTrend, delta) : undefined;
+
   return (
     <div className="rounded-lg border border-neutral-200 p-4 text-center dark:border-neutral-800">
       <dt className="text-xs uppercase tracking-wide text-neutral-500">{label}</dt>
-      <dd className="mt-1 text-2xl font-semibold">{value}</dd>
+      <dd className="mt-1 flex flex-col items-center gap-2">
+        <span className="text-2xl font-semibold">{value}</span>
+        {resolvedTrend && trendMeta && (
+          <Badge variant={trendMeta.variant}>
+            <span aria-hidden="true">
+              {trendMeta.label}
+              {visualDelta ? ` ${visualDelta}` : ""}
+            </span>
+            <span className="sr-only">
+              Trend {resolvedTrend}
+              {visualDelta ? ` by ${Math.abs(delta ?? 0)}` : ""}
+            </span>
+          </Badge>
+        )}
+      </dd>
     </div>
   );
 }

src/components/__tests__/StatTile.test.tsx

@@ -0,0 +1,46 @@
+import { render, screen } from "@testing-library/react";
+import { StatTile } from "../StatTile";
+
+describe("StatTile", () => {
+  it("renders unchanged when no delta or trend is provided", () => {
+    render(<StatTile label="Pairs" value="12" />);
+
+    expect(screen.getByText("Pairs")).toBeInTheDocument();
+    expect(screen.getByText("12")).toBeInTheDocument();
+    expect(screen.queryByText(/Trend /)).not.toBeInTheDocument();
+  });
+
+  it("renders a positive delta as an accessible upward trend", () => {
+    render(<StatTile label="Volume" value="120" delta={8} />);
+
+    const visible = screen.getByText("Up +8");
+    expect(visible).toBeInTheDocument();
+    expect(screen.getByText("Trend up by 8")).toHaveClass("sr-only");
+    expect(visible.parentElement?.className).toMatch(/emerald/);
+  });
+
+  it("renders a negative delta as an accessible downward trend", () => {
+    render(<StatTile label="Errors" value="3" delta={-2} />);
+
+    const visible = screen.getByText("Down -2");
+    expect(visible).toBeInTheDocument();
+    expect(screen.getByText("Trend down by 2")).toHaveClass("sr-only");
+    expect(visible.parentElement?.className).toMatch(/rose/);
+  });
+
+  it("renders zero delta as a flat trend", () => {
+    render(<StatTile label="Routes" value="50" delta={0} />);
+
+    const visible = screen.getByText("Flat 0");
+    expect(visible).toBeInTheDocument();
+    expect(screen.getByText("Trend flat by 0")).toHaveClass("sr-only");
+    expect(visible.parentElement?.className).toMatch(/neutral/);
+  });
+
+  it("can render an explicit trend without a numeric delta", () => {
+    render(<StatTile label="Status" value="Live" trend="up" />);
+
+    expect(screen.getByText("Up")).toBeInTheDocument();
+    expect(screen.getByText("Trend up")).toHaveClass("sr-only");
+  });
+});