@graph8/sdk 0.358.0 → 0.362.0

package/blocks/_foundation/components/screen/detail-panel.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+/**
+ * DetailPanel: the selected record. A sticky header (avatar, title, subtitle, status badges, actions,
+ * close), then either underline tabs (Overview, Activity, Notes...) or plain children. Lives inside
+ * SplitView's detail slot, or on its own as a record page.
+ *
+ * SDK operations: none.
+ */
+import { useEffect, useState, type ReactNode } from "react";
+import { Maximize2, Minimize2, X } from "lucide-react";
+import { Button, Tabs, TabsContent, TabsList, TabsTrigger, cn } from "@graph8/sdk/ui";
+
+export interface DetailTab {
+  id: string;
+  label: ReactNode;
+  content: ReactNode;
+  count?: number;
+}
+
+export interface DetailPanelProps {
+  title: ReactNode;
+  subtitle?: ReactNode;
+  /** Usually <EntityAvatar size="lg" />. */
+  avatar?: ReactNode;
+  /** StatusPills or small facts beside the title. */
+  badges?: ReactNode;
+  /** Buttons or a menu in the header (edit, enroll, delete). */
+  actions?: ReactNode;
+  tabs?: DetailTab[];
+  /** Controlled active tab; otherwise the first tab (or `defaultTab`). */
+  activeTab?: string;
+  defaultTab?: string;
+  onTabChange?: (id: string) => void;
+  onClose?: () => void;
+  /** Shows an "Open full page" button; wire it to `useUrlState("view")` and SplitView `expanded`. */
+  onExpand?: () => void;
+  /** Shows a "Back to split view" button instead of the expand button (full-page mode). */
+  onCollapse?: () => void;
+  children?: ReactNode;
+  /** Shown under the header on every tab (a short fact row, an alert). */
+  summary?: ReactNode;
+  className?: string;
+  bodyClassName?: string;
+}
+
+export const DETAIL_TAB_LIST_CLASS = "h-auto w-full justify-start gap-0 rounded-none border-b border-border bg-transparent p-0";
+export const DETAIL_TAB_TRIGGER_CLASS =
+  "relative -mb-px h-9 rounded-none border-b-2 border-transparent bg-transparent px-3 text-sm font-normal text-text-color-muted shadow-none transition-colors data-[state=active]:border-foreground data-[state=active]:bg-transparent data-[state=active]:font-medium data-[state=active]:text-foreground data-[state=active]:shadow-none hover:text-foreground";
+
+export function DetailPanel({ title, subtitle, avatar, badges, actions, tabs, activeTab, defaultTab, onTabChange, onClose, onExpand, onCollapse, children, summary, className, bodyClassName }: DetailPanelProps) {
+  const first = tabs?.[0]?.id;
+  const [internal, setInternal] = useState(activeTab ?? defaultTab ?? first);
+  useEffect(() => {
+    if (activeTab != null) setInternal(activeTab);
+  }, [activeTab]);
+  const current = activeTab ?? internal ?? first;
+  const change = (id: string) => {
+    if (activeTab == null) setInternal(id);
+    onTabChange?.(id);
+  };
+
+  return (
+    <article className={cn("flex h-full min-h-0 min-w-0 flex-col bg-background", className)} data-testid="detail-panel">
+      <header className="sticky top-0 z-10 shrink-0 border-b border-border bg-background/95 px-5 pb-3 pt-4 backdrop-blur supports-[backdrop-filter]:bg-background/80">
+        <div className="flex items-start gap-3">
+          {avatar ? <div className="shrink-0">{avatar}</div> : null}
+          <div className="min-w-0 flex-1">
+            <h2 className="truncate text-base font-medium leading-6 text-foreground">{title}</h2>
+            {subtitle ? <p className="truncate text-sm text-text-color-muted">{subtitle}</p> : null}
+            {badges ? <div className="mt-1.5 flex flex-wrap items-center gap-1.5">{badges}</div> : null}
+          </div>
+          <div className="flex shrink-0 items-center gap-1">
+            {actions}
+            {onCollapse ? (
+              <Button type="button" variant="ghost" size="icon" className="size-8 text-text-color-muted hover:text-foreground" aria-label="Back to split view" onClick={onCollapse}>
+                <Minimize2 className="size-4" strokeWidth={1.5} aria-hidden />
+              </Button>
+            ) : onExpand ? (
+              <Button type="button" variant="ghost" size="icon" className="size-8 text-text-color-muted hover:text-foreground" aria-label="Open full page" onClick={onExpand}>
+                <Maximize2 className="size-4" strokeWidth={1.5} aria-hidden />
+              </Button>
+            ) : null}
+            {onClose ? (
+              <Button type="button" variant="ghost" size="icon" className="size-8 text-text-color-muted hover:text-foreground" aria-label="Close details" onClick={onClose}>
+                <X className="size-4" strokeWidth={1.5} aria-hidden />
+              </Button>
+            ) : null}
+          </div>
+        </div>
+        {summary ? <div className="mt-3">{summary}</div> : null}
+      </header>
+      {tabs && tabs.length > 0 ? (
+        <Tabs value={current} onValueChange={change} className="flex min-h-0 flex-1 flex-col">
+          <TabsList className={cn(DETAIL_TAB_LIST_CLASS, "shrink-0 overflow-x-auto px-3")} aria-label="Record views">
+            {tabs.map((t) => (
+              <TabsTrigger key={t.id} value={t.id} className={DETAIL_TAB_TRIGGER_CLASS}>
+                {t.label}
+                {t.count != null ? <span className="ml-1.5 rounded-full bg-muted px-1.5 text-[11px] tabular-nums text-text-color-muted">{t.count}</span> : null}
+              </TabsTrigger>
+            ))}
+          </TabsList>
+          {tabs.map((t) => (
+            <TabsContent key={t.id} value={t.id} className={cn("mt-0 min-h-0 flex-1 overflow-y-auto px-5 py-4", bodyClassName)}>
+              {t.content}
+            </TabsContent>
+          ))}
+        </Tabs>
+      ) : (
+        <div className={cn("min-h-0 flex-1 overflow-y-auto px-5 py-4", bodyClassName)}>{children}</div>
+      )}
+    </article>
+  );
+}

package/blocks/_foundation/components/screen/entity-avatar.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+/**
+ * EntityAvatar: the face of a person or the mark of a company in rows, headers and detail panels.
+ * Falls back to initials (person) or the first letter (company); companies are rounded squares,
+ * people are circles, so the two read differently at a glance.
+ *
+ * SDK operations: none.
+ */
+import { Building, UserRound } from "lucide-react";
+import { Avatar, AvatarFallback, AvatarImage, cn } from "@graph8/sdk/ui";
+
+export interface EntityAvatarProps {
+  name: string;
+  imageUrl?: string | null;
+  kind?: "person" | "company";
+  size?: "sm" | "md" | "lg";
+  className?: string;
+}
+
+const SIZE: Record<NonNullable<EntityAvatarProps["size"]>, { box: string; text: string; icon: string }> = {
+  sm: { box: "size-6", text: "text-[10px]", icon: "size-3" },
+  md: { box: "size-8", text: "text-xs", icon: "size-4" },
+  lg: { box: "size-11", text: "text-sm", icon: "size-5" },
+};
+
+/** "Ada Lovelace" -> "AL"; "graph8" -> "G"; "" -> "". */
+export function initialsFor(name: string, kind: "person" | "company" = "person"): string {
+  const words = String(name ?? "")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  if (!words.length) return "";
+  if (kind === "company") return words[0].charAt(0).toUpperCase();
+  const first = words[0].charAt(0);
+  const last = words.length > 1 ? words[words.length - 1].charAt(0) : "";
+  return `${first}${last}`.toUpperCase();
+}
+
+export function EntityAvatar({ name, imageUrl, kind = "person", size = "md", className }: EntityAvatarProps) {
+  const s = SIZE[size] ?? SIZE.md;
+  const initials = initialsFor(name, kind);
+  const shape = kind === "company" ? "rounded-md" : "rounded-full";
+  const Icon = kind === "company" ? Building : UserRound;
+  return (
+    <Avatar data-kind={kind} className={cn(s.box, shape, "shrink-0 border border-border", className)}>
+      {imageUrl ? <AvatarImage src={imageUrl} alt="" className={cn("object-cover", shape)} /> : null}
+      <AvatarFallback
+        aria-label={name || (kind === "company" ? "Company" : "Person")}
+        className={cn(shape, "bg-muted font-medium uppercase tracking-wide text-foreground", s.text)}
+      >
+        {initials || <Icon className={cn(s.icon, "text-text-color-muted")} strokeWidth={1.5} aria-hidden />}
+      </AvatarFallback>
+    </Avatar>
+  );
+}

package/blocks/_foundation/components/screen/form-sheet.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+/**
+ * FormSheet: the create/edit side sheet. Header (title, description), a scrolling body for the form
+ * fields, and a sticky footer for Cancel and the one primary action. Built on the UI kit's Sheet
+ * (Radix Dialog in a portal), so ConfirmSpendDialog can stack on top of it.
+ *
+ * SDK operations: none.
+ */
+import type { FormEvent, ReactNode } from "react";
+import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, cn } from "@graph8/sdk/ui";
+
+export interface FormSheetProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title: ReactNode;
+  description?: ReactNode;
+  children: ReactNode;
+  /** Buttons: Cancel first, the primary action last. */
+  footer?: ReactNode;
+  /** Wrap the body in a <form>; Enter in a field submits. */
+  onSubmit?: (event: FormEvent<HTMLFormElement>) => void;
+  width?: "md" | "lg" | "xl";
+  side?: "right" | "left";
+  /** Keep the sheet open on outside clicks (unsaved work). Default true. */
+  blockOutsideClick?: boolean;
+  className?: string;
+  bodyClassName?: string;
+}
+
+const WIDTH: Record<NonNullable<FormSheetProps["width"]>, string> = {
+  md: "sm:max-w-md",
+  lg: "sm:max-w-lg",
+  xl: "sm:max-w-2xl",
+};
+
+export function FormSheet({ open, onOpenChange, title, description, children, footer, onSubmit, width = "md", side = "right", blockOutsideClick = true, className, bodyClassName }: FormSheetProps) {
+  const bodyClass = "flex min-h-0 flex-1 flex-col";
+  const body = (
+    <>
+      <div className={cn("min-h-0 flex-1 space-y-4 overflow-y-auto px-5 py-4", bodyClassName)}>{children}</div>
+      {footer ? <div className="flex shrink-0 items-center justify-end gap-2 border-t border-border bg-background px-5 py-3">{footer}</div> : null}
+    </>
+  );
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent
+        side={side}
+        data-testid="form-sheet"
+        className={cn("flex w-full flex-col gap-0 p-0 sm:w-full", WIDTH[width] ?? WIDTH.md, className)}
+        onInteractOutside={(e) => (blockOutsideClick ? e.preventDefault() : undefined)}
+      >
+        <SheetHeader className="shrink-0 gap-1 border-b border-border px-5 py-4 pr-12 text-left">
+          <SheetTitle className="text-base font-medium leading-6 text-foreground">{title}</SheetTitle>
+          {description ? <SheetDescription className="text-sm text-text-color-muted">{description}</SheetDescription> : <SheetDescription className="sr-only">Form</SheetDescription>}
+        </SheetHeader>
+        {onSubmit ? (
+          <form
+            onSubmit={(e: FormEvent<HTMLFormElement>) => {
+              e.preventDefault();
+              onSubmit(e);
+            }}
+            className={bodyClass}
+          >
+            {body}
+          </form>
+        ) : (
+          <div className={bodyClass}>{body}</div>
+        )}
+      </SheetContent>
+    </Sheet>
+  );
+}

package/blocks/_foundation/components/screen/index.ts

@@ -0,0 +1,21 @@
+"use client";
+
+/**
+ * The screen kit in one import: `import { ScreenLayout, SplitView, ... } from "@/g8/components/screen"`.
+ * Each part also has its own file (`@/g8/components/screen/split-view`) for smaller bundles.
+ *
+ * SDK operations: none.
+ */
+export * from "./bar-list";
+export * from "./detail-panel";
+export * from "./entity-avatar";
+export * from "./form-sheet";
+export * from "./key-value-list";
+export * from "./screen-layout";
+export * from "./section-card";
+export * from "./sparkline";
+export * from "./split-view";
+export * from "./stat-strip";
+export * from "./status-pill";
+export * from "./time-series-chart";
+export * from "./toolbar";

package/blocks/_foundation/components/screen/key-value-list.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+/**
+ * KeyValueList: labelled facts about one record (email, owner, stage, created), one or two columns.
+ * A missing value is a faint dash, never "N/A" or "Unknown"; a real zero reads "0".
+ *
+ * SDK operations: none.
+ */
+import type { ReactNode } from "react";
+import { cn } from "@graph8/sdk/ui";
+
+export interface KeyValueItem {
+  label: string;
+  value: ReactNode;
+  /** Span both columns (long text, addresses). */
+  wide?: boolean;
+  /** Render the value in a monospaced font (ids, domains). */
+  mono?: boolean;
+}
+
+export interface KeyValueListProps {
+  items: KeyValueItem[];
+  columns?: 1 | 2;
+  /** Put labels beside values instead of above them (dense, one column). */
+  inline?: boolean;
+  className?: string;
+}
+
+export function isEmptyValue(value: ReactNode): boolean {
+  return value == null || value === "" || value === false;
+}
+
+/** The faint dash the kit shows for an unknown value. */
+export function EmptyValue({ className }: { className?: string }) {
+  return (
+    <span aria-label="No value" className={cn("text-border select-none", className)} data-empty="true">
+      -
+    </span>
+  );
+}
+
+export function KeyValueList({ items, columns = 1, inline, className }: KeyValueListProps) {
+  return (
+    <dl
+      className={cn(
+        "grid gap-x-6",
+        inline ? "gap-y-2" : "gap-y-3",
+        columns === 2 && !inline ? "sm:grid-cols-2" : "grid-cols-1",
+        className,
+      )}
+    >
+      {items.map((item, i) => (
+        <div
+          key={`${item.label}-${i}`}
+          className={cn("min-w-0", inline ? "grid grid-cols-[minmax(6rem,9rem)_1fr] items-baseline gap-3" : "", item.wide && columns === 2 && "sm:col-span-2")}
+        >
+          <dt className={cn("truncate text-xs text-text-color-muted", inline ? "" : "mb-0.5")}>{item.label}</dt>
+          <dd className={cn("min-w-0 break-words text-sm text-foreground", item.mono && "font-mono text-[13px]")}>
+            {isEmptyValue(item.value) ? <EmptyValue /> : item.value}
+          </dd>
+        </div>
+      ))}
+    </dl>
+  );
+}

package/blocks/_foundation/components/screen/screen-layout.tsx

@@ -0,0 +1,124 @@
+"use client";
+
+/**
+ * ScreenLayout: the frame of a finished screen. A sticky header (icon, title, description, actions,
+ * optional underline tabs), then stats, then the toolbar, then the content filling the rest. Use one
+ * per route; the app shell provides the sidebar and the workspace header around it.
+ *
+ * SDK operations: none.
+ */
+import { useRef, type KeyboardEvent, type ReactNode } from "react";
+import { cn } from "@graph8/sdk/ui";
+import { StatStrip, type StatItem } from "./stat-strip";
+
+export interface ScreenTab {
+  id: string;
+  label: ReactNode;
+  count?: number;
+  disabled?: boolean;
+}
+
+export interface ScreenLayoutProps {
+  title: ReactNode;
+  description?: ReactNode;
+  /** A lucide icon element (size 16 to 20) shown in an ink well before the title. */
+  icon?: ReactNode;
+  /** Right-aligned header actions; the one primary action goes last. */
+  actions?: ReactNode;
+  tabs?: ScreenTab[];
+  activeTab?: string;
+  onTabChange?: (id: string) => void;
+  stats?: StatItem[];
+  statsLoading?: boolean;
+  toolbar?: ReactNode;
+  children: ReactNode;
+  /** Breadcrumb or context line above the title ("Contacts / Lists"). */
+  eyebrow?: ReactNode;
+  /** Let the content scroll inside the frame (lists with their own scroll) instead of the page. */
+  fill?: boolean;
+  /** Horizontal padding scale. "none" when the content draws its own edges (tables, kanban). */
+  padding?: "default" | "none";
+  className?: string;
+  contentClassName?: string;
+}
+
+export function ScreenTabs({ tabs, activeTab, onTabChange, className }: { tabs: ScreenTab[]; activeTab?: string; onTabChange?: (id: string) => void; className?: string }) {
+  const refs = useRef<Array<HTMLButtonElement | null>>([]);
+  const current = activeTab ?? tabs[0]?.id;
+  const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    const enabled = tabs.map((t, i) => (t.disabled ? -1 : i)).filter((i) => i >= 0);
+    const at = enabled.indexOf(tabs.findIndex((t) => t.id === current));
+    let next = -1;
+    if (e.key === "ArrowRight") next = enabled[(at + 1) % enabled.length];
+    else if (e.key === "ArrowLeft") next = enabled[(at - 1 + enabled.length) % enabled.length];
+    else if (e.key === "Home") next = enabled[0];
+    else if (e.key === "End") next = enabled[enabled.length - 1];
+    if (next < 0 || next === undefined) return;
+    e.preventDefault();
+    refs.current[next]?.focus();
+    onTabChange?.(tabs[next].id);
+  };
+  return (
+    <div role="tablist" aria-label="Views" onKeyDown={onKeyDown} className={cn("-mb-px flex items-end gap-0 overflow-x-auto", className)}>
+      {tabs.map((t, i) => {
+        const active = t.id === current;
+        return (
+          <button
+            key={t.id}
+            ref={(el) => { refs.current[i] = el; }}
+            type="button"
+            role="tab"
+            aria-selected={active}
+            aria-disabled={t.disabled || undefined}
+            disabled={t.disabled}
+            tabIndex={active ? 0 : -1}
+            onClick={() => (!t.disabled ? onTabChange?.(t.id) : undefined)}
+            className={cn(
+              "relative inline-flex h-9 shrink-0 items-center gap-1.5 whitespace-nowrap border-b-2 px-3 text-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+              active ? "border-foreground font-medium text-foreground" : "border-transparent text-text-color-muted hover:text-foreground",
+              t.disabled && "opacity-50",
+            )}
+          >
+            {t.label}
+            {t.count != null ? (
+              <span className={cn("rounded-full px-1.5 text-[11px] leading-4 tabular-nums", active ? "bg-foreground/10 text-foreground" : "bg-muted text-text-color-muted")}>{t.count}</span>
+            ) : null}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+export function ScreenLayout({ title, description, icon, actions, tabs, activeTab, onTabChange, stats, statsLoading, toolbar, children, eyebrow, fill, padding = "default", className, contentClassName }: ScreenLayoutProps) {
+  const px = padding === "none" ? "" : "px-4 sm:px-6";
+  return (
+    <section className={cn("flex w-full min-w-0 flex-col", fill ? "h-full min-h-0" : "min-h-full", className)} data-testid="screen-layout">
+      <header className={cn("sticky top-0 z-20 shrink-0 border-b border-border bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/80", padding === "none" ? "px-4 sm:px-6" : px)}>
+        <div className={cn("flex items-start justify-between gap-4 pt-4", tabs?.length ? "pb-2" : "pb-3")}>
+          <div className="flex min-w-0 items-center gap-3">
+            {icon ? (
+              <span className="flex size-9 shrink-0 items-center justify-center rounded-lg border border-border bg-muted text-foreground [&_svg]:size-[18px]" aria-hidden>
+                {icon}
+              </span>
+            ) : null}
+            <div className="min-w-0">
+              {eyebrow ? <div className="mb-0.5 truncate text-xs text-text-color-muted">{eyebrow}</div> : null}
+              <h1 className="truncate text-lg font-medium leading-6 tracking-tight text-foreground">{title}</h1>
+              {description ? <p className="mt-0.5 truncate text-sm text-text-color-muted">{description}</p> : null}
+            </div>
+          </div>
+          {actions ? <div className="flex shrink-0 flex-wrap items-center justify-end gap-2">{actions}</div> : null}
+        </div>
+        {tabs && tabs.length > 0 ? <ScreenTabs tabs={tabs} activeTab={activeTab} onTabChange={onTabChange} /> : null}
+      </header>
+      {stats || statsLoading ? (
+        <div className={cn("shrink-0 py-4", padding === "none" ? "px-4 sm:px-6" : px)}>
+          <StatStrip items={stats ?? []} loading={statsLoading} />
+        </div>
+      ) : null}
+      {toolbar ? <div className={cn("shrink-0 pb-3", padding === "none" ? "px-4 sm:px-6" : px, stats || statsLoading ? "" : "pt-4")}>{toolbar}</div> : null}
+      <div className={cn("min-h-0 min-w-0 flex-1", fill ? "overflow-hidden" : "", px, toolbar || stats || statsLoading ? "pb-6" : "py-4 pb-6", contentClassName)}>{children}</div>
+    </section>
+  );
+}

package/blocks/_foundation/components/screen/section-card.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+/**
+ * SectionCard: a flat, hairlined section with a title row (title, description, actions) and a body.
+ * Use it to group facts, lists or a form inside a screen or a detail panel. No shadow: cards in
+ * graph8 are flat; only floating layers cast shadows.
+ *
+ * SDK operations: none.
+ */
+import type { ReactNode } from "react";
+import { cn } from "@graph8/sdk/ui";
+
+export interface SectionCardProps {
+  title: ReactNode;
+  description?: ReactNode;
+  /** Buttons or a menu, right-aligned in the title row. */
+  actions?: ReactNode;
+  /** Leading icon beside the title (14 to 16px). */
+  icon?: ReactNode;
+  children: ReactNode;
+  /** Remove the body padding (tables, lists that draw their own rows). */
+  flush?: boolean;
+  /** Optional footer row (pager, totals, a secondary action). */
+  footer?: ReactNode;
+  className?: string;
+  bodyClassName?: string;
+  id?: string;
+}
+
+export function SectionCard({ title, description, actions, icon, children, flush, footer, className, bodyClassName, id }: SectionCardProps) {
+  return (
+    <section id={id} className={cn("flex min-w-0 flex-col overflow-hidden rounded-lg border border-border bg-card text-card-foreground", className)}>
+      <header className="flex items-start justify-between gap-3 border-b border-border px-4 py-2.5">
+        <div className="flex min-w-0 items-start gap-2">
+          {icon ? <span className="mt-0.5 shrink-0 text-text-color-muted [&_svg]:size-4">{icon}</span> : null}
+          <div className="min-w-0">
+            <h3 className="truncate text-sm font-medium leading-5 text-foreground">{title}</h3>
+            {description ? <p className="mt-0.5 text-xs leading-4 text-text-color-muted">{description}</p> : null}
+          </div>
+        </div>
+        {actions ? <div className="flex shrink-0 items-center gap-1.5">{actions}</div> : null}
+      </header>
+      <div className={cn("min-w-0", flush ? "" : "p-4", bodyClassName)}>{children}</div>
+      {footer ? <footer className="border-t border-border px-4 py-2 text-xs text-text-color-muted">{footer}</footer> : null}
+    </section>
+  );
+}

package/blocks/_foundation/components/screen/sparkline.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+/**
+ * Sparkline: a tiny inline trend (ink line at 38%, area at 6%) for stat tiles and table cells.
+ * Pure SVG, no chart library. Scales to its box; pass `className` for the size.
+ *
+ * SDK operations: none.
+ */
+import { useId } from "react";
+import { cn } from "@graph8/sdk/ui";
+import { TONE_CLASSES, type Tone } from "./status-pill";
+
+export interface SparklineProps {
+  data: number[];
+  /** Colour of the line. Default is ink; use a tone only when the direction means good or bad. */
+  tone?: Tone;
+  /** Fill the area under the line (ink at 6%). */
+  area?: boolean;
+  /** Mark the last point. */
+  endDot?: boolean;
+  className?: string;
+  /** Accessible summary ("Replies, last 14 days"). */
+  label?: string;
+}
+
+const TONE_TEXT: Record<Tone, string> = {
+  neutral: "text-foreground/40",
+  info: TONE_CLASSES.info.text,
+  positive: TONE_CLASSES.positive.text,
+  warning: TONE_CLASSES.warning.text,
+  negative: TONE_CLASSES.negative.text,
+};
+
+/** Points scaled into a 100x32 box; a flat series draws a mid line. */
+export function sparklinePoints(data: number[], width = 100, height = 32, pad = 2): Array<[number, number]> {
+  const values = data.filter((v) => Number.isFinite(v));
+  if (values.length === 0) return [];
+  if (values.length === 1) values.push(values[0]);
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const span = max - min || 1;
+  const stepX = (width - pad * 2) / (values.length - 1);
+  return values.map((v, i) => [pad + i * stepX, height - pad - ((v - min) / span) * (height - pad * 2)]);
+}
+
+export function Sparkline({ data, tone = "neutral", area = true, endDot = true, className, label }: SparklineProps) {
+  const id = useId();
+  const pts = sparklinePoints(data);
+  if (pts.length === 0) return <span aria-hidden className={cn("inline-block h-8 w-20", className)} />;
+  const line = pts.map(([x, y]) => `${x.toFixed(1)},${y.toFixed(1)}`).join(" ");
+  const first = pts[0];
+  const last = pts[pts.length - 1];
+  const areaPath = `M${first[0].toFixed(1)},32 L${line.replace(/ /g, " L")} L${last[0].toFixed(1)},32 Z`;
+  return (
+    <svg
+      viewBox="0 0 100 32"
+      preserveAspectRatio="none"
+      role={label ? "img" : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
+      className={cn("h-8 w-20 overflow-visible", TONE_TEXT[tone] ?? TONE_TEXT.neutral, className)}
+      data-testid="sparkline"
+    >
+      {area ? <path d={areaPath} fill="currentColor" fillOpacity={0.12} stroke="none" /> : null}
+      <polyline
+        points={line}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={1.5}
+        strokeLinejoin="round"
+        strokeLinecap="round"
+        vectorEffect="non-scaling-stroke"
+      />
+      {endDot ? <circle id={id} cx={last[0]} cy={last[1]} r={2} fill="currentColor" vectorEffect="non-scaling-stroke" /> : null}
+    </svg>
+  );
+}