cortena-ui 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortena-ui",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Cortena UI — the shared React component library for cortenaweb and every Cortena extension. shadcn over Base UI, styled entirely from cortena-design tokens.",
   "license": "UNLICENSED",
   "repository": {

package/src/components/alert.tsx

@@ -8,7 +8,13 @@ import { cn } from "@/lib/cn";
  * Alert — an inline callout. Tinted variants use the `-soft` fill for the
  * background and the tone colour for the border and icon; the body text stays
  * on the foreground token so it reads in both themes.
+ *
+ * The error tone is `destructive`, the same spelling Button uses; `danger` is
+ * a deprecated alias of it and paints identically.
  */
+const DESTRUCTIVE_ALERT =
+  "bg-[var(--ds-destructive-soft)] border-[var(--ds-destructive)]/35 [&_[data-slot=alert-icon]]:text-[color:var(--ds-destructive)]";
+
 const alertVariants = cva(
   [
     "flex gap-3 rounded-[var(--ds-radius-md)] border px-3.5 py-3",
@@ -23,8 +29,9 @@ const alertVariants = cva(
         success:
           "bg-[var(--ds-success-soft)] border-[var(--ds-success)]/35 [&_[data-slot=alert-icon]]:text-[color:var(--ds-success)]",
         warn: "bg-[var(--ds-warning-soft)] border-[var(--ds-warning)]/35 [&_[data-slot=alert-icon]]:text-[color:var(--ds-warning)]",
-        danger:
-          "bg-[var(--ds-destructive-soft)] border-[var(--ds-destructive)]/35 [&_[data-slot=alert-icon]]:text-[color:var(--ds-destructive)]",
+        destructive: DESTRUCTIVE_ALERT,
+        /** @deprecated Use `destructive`, the name Button and Badge use; this alias paints the same. */
+        danger: DESTRUCTIVE_ALERT,
         info: "bg-[var(--ds-info-soft)] border-[var(--ds-info)]/35 [&_[data-slot=alert-icon]]:text-[color:var(--ds-info)]",
       },
     },

package/src/components/badge.tsx

@@ -6,9 +6,12 @@ import { cn } from "@/lib/cn";
 
 /**
  * Badge — the mono, uppercase status label. Each tone pairs a `-soft` fill
- * with its foreground token; `warn`, `danger` and `secondary` are aliases kept
- * for cortenaweb call sites.
+ * with its foreground token. The error tone is `destructive`, the same
+ * spelling Button and Alert use; `warn`, `danger` and `secondary` are
+ * deprecated aliases kept for cortenaweb call sites and paint identically.
  */
+const DESTRUCTIVE_BADGE = "bg-[var(--ds-destructive-soft)] text-[color:var(--ds-destructive)]";
+
 const badgeVariants = cva(
   [
     "inline-flex items-center gap-1.5 px-1.5 py-0.5 whitespace-nowrap",
@@ -23,9 +26,11 @@ const badgeVariants = cva(
         default: "bg-[var(--ds-primary-soft)] text-[color:var(--ds-primary-soft-foreground)]",
         success: "bg-[var(--ds-success-soft)] text-[color:var(--ds-success)]",
         warning: "bg-[var(--ds-warning-soft)] text-[color:var(--ds-warning)]",
+        /** @deprecated Use `warning`; this alias paints the same. */
         warn: "bg-[var(--ds-warning-soft)] text-[color:var(--ds-warning)]",
-        danger: "bg-[var(--ds-destructive-soft)] text-[color:var(--ds-destructive)]",
-        destructive: "bg-[var(--ds-destructive-soft)] text-[color:var(--ds-destructive)]",
+        destructive: DESTRUCTIVE_BADGE,
+        /** @deprecated Use `destructive`, the name Button and Alert use; this alias paints the same. */
+        danger: DESTRUCTIVE_BADGE,
         info: "bg-[var(--ds-info-soft)] text-[color:var(--ds-info)]",
         neutral: "bg-[var(--ds-hover)] text-[color:var(--ds-muted-foreground)]",
         secondary: "bg-[var(--ds-hover)] text-[color:var(--ds-muted-foreground)]",

package/src/components/breadcrumb.tsx

@@ -0,0 +1,171 @@
+"use client";
+
+import { ChevronRight, MoreHorizontal } from "lucide-react";
+import type * as React from "react";
+import { cn } from "@/lib/cn";
+import { renderWith, type RenderProp } from "@/lib/render";
+
+/**
+ * Breadcrumb — the trail above a page title.
+ *
+ * A `<nav aria-label="Breadcrumb">` around an ordered list, which is what
+ * assistive technology expects: the list order is the hierarchy, so a screen
+ * reader announces "list, 4 items" and reads the path in order. Separators are
+ * decorative list items, not text inside the links, so a link's accessible
+ * name is the crumb and nothing else.
+ *
+ * The last crumb is `BreadcrumbPage`, not a link: it is the page you are on,
+ * so it carries `aria-current="page"` and is not focusable. Everything before
+ * it is a `BreadcrumbLink`.
+ *
+ * ```tsx
+ * <Breadcrumb>
+ *   <BreadcrumbList>
+ *     <BreadcrumbItem>
+ *       <BreadcrumbLink href="/">Home</BreadcrumbLink>
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem>
+ *       <BreadcrumbEllipsis />
+ *     </BreadcrumbItem>
+ *     <BreadcrumbSeparator />
+ *     <BreadcrumbItem>
+ *       <BreadcrumbPage>Invoice 4021</BreadcrumbPage>
+ *     </BreadcrumbItem>
+ *   </BreadcrumbList>
+ * </Breadcrumb>
+ * ```
+ *
+ * **Router links.** `BreadcrumbLink` renders an `<a>` by default. Pass
+ * `render` with the router's link component and the class name, `href` and
+ * handlers are merged onto it, the same contract as `ButtonLink`:
+ * `render={<NextLink href="/projects" />}` or
+ * `render={<Link to="/projects" />}`. This is deliberately not Base UI's
+ * `render` — a breadcrumb is markup, not a Base UI primitive — but it takes
+ * the same shape so there is one thing to remember.
+ */
+function Breadcrumb({ className, ...props }: React.ComponentProps<"nav">) {
+  return (
+    <nav
+      data-slot="breadcrumb"
+      aria-label="Breadcrumb"
+      className={cn("min-w-0", className)}
+      {...props}
+    />
+  );
+}
+
+function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
+  return (
+    <ol
+      data-slot="breadcrumb-list"
+      className={cn(
+        "flex flex-wrap items-center gap-1.5 break-words p-0 sm:gap-2",
+        "list-none text-[length:var(--ds-text-caption-lg)]",
+        "leading-[var(--ds-text-caption-lg--line-height)] text-[color:var(--ds-muted-foreground)]",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="breadcrumb-item"
+      className={cn("inline-flex min-w-0 items-center gap-1.5", className)}
+      {...props}
+    />
+  );
+}
+
+export interface BreadcrumbLinkProps extends React.ComponentProps<"a"> {
+  /** Replace the rendered `<a>` with a router link; props are merged onto it. */
+  render?: RenderProp;
+}
+
+function BreadcrumbLink({ className, render, children, ...props }: BreadcrumbLinkProps) {
+  const merged = {
+    ...props,
+    "data-slot": "breadcrumb-link",
+    className: cn(
+      "truncate rounded-[var(--ds-radius-sm)] text-[color:var(--ds-muted-foreground)] no-underline",
+      "transition-colors duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]",
+      "hover:text-[color:var(--ds-foreground)] hover:underline underline-offset-4",
+      "outline-none focus-visible:ring-[3px] focus-visible:ring-[var(--ds-ring)]/40",
+      "[&_svg]:size-3.5 [&_svg]:shrink-0",
+      className,
+    ),
+  };
+  return renderWith(render, merged, children, "a");
+}
+
+/**
+ * The current page: the last crumb, which is not a link.
+ *
+ * A plain `<span aria-current="page">`, deliberately not `role="link"` with
+ * `aria-disabled` — a disabled link that cannot be focused is a fiction, and
+ * it makes `getByRole("link")` return a crumb that navigates nowhere. With a
+ * span, the roles in the trail are exactly the crumbs you can travel to.
+ */
+function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="breadcrumb-page"
+      aria-current="page"
+      className={cn("truncate font-medium text-[color:var(--ds-foreground)]", className)}
+      {...props}
+    />
+  );
+}
+
+/** Decorative divider between two crumbs; a chevron unless children replace it. */
+function BreadcrumbSeparator({ className, children, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="breadcrumb-separator"
+      role="presentation"
+      aria-hidden="true"
+      className={cn(
+        "inline-flex shrink-0 items-center text-[color:var(--ds-text-tertiary)] [&_svg]:size-3.5",
+        className,
+      )}
+      {...props}
+    >
+      {children ?? <ChevronRight />}
+    </li>
+  );
+}
+
+/**
+ * Stands in for the crumbs a long trail collapses; put it inside a
+ * BreadcrumbItem. The glyph is hidden and the label is not: an ellipsis that
+ * announces nothing leaves a screen-reader user with a gap in the path.
+ */
+function BreadcrumbEllipsis({ className, children, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="breadcrumb-ellipsis"
+      className={cn(
+        "inline-flex size-5 items-center justify-center text-[color:var(--ds-text-tertiary)]",
+        "[&_svg]:size-3.5",
+        className,
+      )}
+      {...props}
+    >
+      <MoreHorizontal aria-hidden />
+      <span className="sr-only">{children ?? "More levels"}</span>
+    </span>
+  );
+}
+
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+};

package/src/components/button-link.tsx

@@ -2,6 +2,7 @@
 
 import type * as React from "react";
 import { cn } from "@/lib/cn";
+import { renderWith, type RenderProp } from "@/lib/render";
 import { buttonVariants, type ButtonProps } from "@/components/button";
 
 /**
@@ -22,7 +23,7 @@ export interface ButtonLinkProps
     Pick<ButtonProps, "variant" | "size"> {
   children?: React.ReactNode;
   /** Replace the rendered `<a>` with a router link; props are merged onto it. */
-  render?: React.ReactElement<Record<string, unknown>>;
+  render?: RenderProp;
   disabled?: boolean;
 }
 
@@ -35,15 +36,7 @@ function ButtonLink({ className, variant, size, render, disabled, children, ...p
     "aria-disabled": disabled || undefined,
     tabIndex: disabled ? -1 : props.tabIndex,
   };
-  if (render) {
-    const Element = render.type as React.ElementType;
-    return (
-      <Element {...(render.props as Record<string, unknown>)} {...merged}>
-        {children ?? (render.props as { children?: React.ReactNode }).children}
-      </Element>
-    );
-  }
-  return <a {...merged}>{children}</a>;
+  return renderWith(render, merged, children, "a");
 }
 
 export { ButtonLink };

package/src/components/card.tsx

@@ -2,28 +2,46 @@
 
 import type * as React from "react";
 import { cn } from "@/lib/cn";
+import { renderWith, type RenderProp } from "@/lib/render";
 
 export interface CardProps extends React.ComponentProps<"div"> {
   /** Lift the border and surface on hover, for clickable cards. */
   hover?: boolean;
   /** Draw the border in the ring colour, for a selected or highlighted card. */
   accent?: boolean;
+  /**
+   * Replace the rendered `<div>` with another element, so a card can *be* the
+   * landmark rather than sit inside a wrapper that is one:
+   * `render={<aside />}` for a sidebar panel, `render={<section />}` (with an
+   * `aria-labelledby` pointing at its title) for a labelled region,
+   * `render={<article />}` for a self-contained item in a feed. Props set on
+   * the passed element come through; the card's own styling wins.
+   */
+  render?: RenderProp;
 }
 
-function Card({ className, hover, accent, ...props }: CardProps) {
-  return (
-    <div
-      data-slot="card"
-      data-accent={accent ? "" : undefined}
-      className={cn(
+/**
+ * Card — the bordered surface everything else sits on. `render` changes the
+ * element without changing the look, which is how a card becomes a landmark.
+ */
+function Card({ className, hover, accent, render, children, ...props }: CardProps) {
+  return renderWith(
+    render,
+    {
+      // data-slot first: SectionCard (and any other composer) overrides it.
+      "data-slot": "card",
+      "data-accent": accent ? "" : undefined,
+      ...props,
+      className: cn(
         "flex flex-col rounded-[var(--ds-radius-lg)] border bg-[var(--ds-card)] text-[color:var(--ds-foreground)]",
         "transition-[border-color,background-color] duration-[var(--ds-duration-fast)] ease-[var(--ds-ease-out)]",
         accent ? "border-[var(--ds-ring)]" : "border-[var(--ds-border-subtle)]",
         hover && "hover:border-[var(--ds-border)] hover:bg-[var(--ds-popover)]",
         className,
-      )}
-      {...props}
-    />
+      ),
+    },
+    children,
+    "div",
   );
 }
 

package/src/components/chart/chart.tsx

@@ -3,13 +3,14 @@
 import * as React from "react";
 import { cn } from "@/lib/cn";
 import { ChartContainer, ChartEmpty, ChartError, ChartLoading, type ChartContainerProps } from "./container";
-import { configFor, isEmptyData, isSeriesArray, toRows, toSlices } from "./data";
+import { configFor, isEmptyData, isMatrix, isSeriesArray, toRows, toSlices } from "./data";
 import { NivoChart, type NivoType } from "./nivo-charts";
 import { RechartsChart, type RechartsType } from "./recharts-charts";
 import {
   chartEngine,
   type ChartConfig,
   type ChartDataFor,
+  type ChartMatrix,
   type ChartRenderer,
   type ChartRow,
   type ChartScale,
@@ -67,9 +68,11 @@ function seriesKeys(type: ChartType, data: unknown, indexBy?: string, keys?: str
     case "donut":
     case "funnel":
       return toSlices(data as ChartSlice[]).map((s) => s.id);
+    case "heatmap":
+      if (isMatrix(data)) return data.rows.map(String);
+      return isSeriesArray(data) ? data.map((s) => String(s.id)) : [];
     case "scatter":
     case "scatterplot":
-    case "heatmap":
       return isSeriesArray(data) ? data.map((s) => String(s.id)) : [];
     case "treemap":
     case "sunburst":
@@ -101,6 +104,14 @@ class ChunkBoundary extends React.Component<
  * Colours, fonts, axes, grid, tooltip, legend and the empty, loading and
  * error states all come from cortena-design tokens; a consumer passes data
  * and, optionally, a `config` of labels.
+ *
+ * `heatmap` takes either the Nivo series shape or a categorical
+ * {@link ChartMatrix} — `{ rows, columns, values }` — for the correlation and
+ * confusion matrices that are already in that form.
+ *
+ * `testMode` gives the drawing area a 600×300 floor so a chart still draws
+ * where the layout gives it no size; see {@link ChartContainerProps.testMode}
+ * and README.md, "Charts in tests".
  */
 function Chart<T extends ChartType>({
   type,

package/src/components/chart/container.tsx

@@ -57,9 +57,26 @@ export interface ChartContainerProps extends Omit<React.ComponentProps<"div">, "
    * `responsive={false}`.
    */
   responsive?: boolean;
+  /**
+   * Give the drawing area a floor of 600×300 so it draws where the layout
+   * gives it none.
+   *
+   * Both engines size themselves from the parent box. Under jsdom nothing has
+   * layout — every element measures 0×0 — so a page test that renders a screen
+   * containing a Chart gets an empty `<div>` and can assert nothing about it.
+   * `testMode` sets `min-width` / `min-height` on the container and hands the
+   * same floor to Recharts' ResponsiveContainer, so the chart draws at
+   * 600×300. It is a floor, not a fixed size: a parent that *does* give the
+   * chart 900px still gets 900px, so a screenshot test is unaffected.
+   */
+  testMode?: boolean;
   children: React.ReactNode;
 }
 
+/** The box `testMode` falls back to when the layout gives the chart none. */
+const TEST_WIDTH = 600;
+const TEST_HEIGHT = 300;
+
 /**
  * ChartContainer — the sized, token-styled surface every chart draws in.
  *
@@ -72,6 +89,7 @@ function ChartContainer({
   config = {},
   height = 300,
   responsive = true,
+  testMode = false,
   className,
   style,
   children,
@@ -90,6 +108,7 @@ function ChartContainer({
       <div
         ref={setElement}
         data-slot="chart"
+        data-test-mode={testMode ? "" : undefined}
         className={cn(
           "relative w-full min-w-0 overflow-hidden text-[length:var(--ds-text-caption-sm)] text-[color:var(--ds-foreground)]",
           responsive ? "flex justify-center" : "block [&>div]:h-full [&>div]:w-full",
@@ -113,11 +132,23 @@ function ChartContainer({
           "[&_text]:font-[family-name:var(--ds-font-body)]",
           className,
         )}
-        style={{ height, ...vars, ...style } as React.CSSProperties}
+        style={
+          {
+            height,
+            ...(testMode ? { minWidth: TEST_WIDTH, minHeight: TEST_HEIGHT } : null),
+            ...vars,
+            ...style,
+          } as React.CSSProperties
+        }
         {...props}
       >
         {responsive ? (
-          <ResponsiveContainer width="100%" height="100%">
+          <ResponsiveContainer
+            width="100%"
+            height="100%"
+            minWidth={testMode ? TEST_WIDTH : undefined}
+            minHeight={testMode ? TEST_HEIGHT : undefined}
+          >
             {children as React.ReactElement}
           </ResponsiveContainer>
         ) : (

package/src/components/chart/data.ts

@@ -1,4 +1,4 @@
-import type { ChartConfig, ChartRow, ChartSeries, ChartSlice, ChartTree } from "./types";
+import type { ChartConfig, ChartMatrix, ChartRow, ChartSeries, ChartSlice, ChartTree } from "./types";
 
 /** True for the `{ id, data: [{ x, y }] }[]` series shape. */
 export function isSeriesArray(data: unknown): data is ChartSeries[] {
@@ -9,6 +9,29 @@ export function isSeriesArray(data: unknown): data is ChartSeries[] {
   );
 }
 
+/** True for the `{ rows, columns, values }` categorical matrix shape. */
+export function isMatrix(data: unknown): data is ChartMatrix {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+  const m = data as ChartMatrix;
+  return Array.isArray(m.rows) && Array.isArray(m.columns) && Array.isArray(m.values);
+}
+
+/**
+ * Pivot a categorical matrix onto the Nivo heatmap shape. Every row gets a
+ * point for every column so the grid stays rectangular; a missing or
+ * non-finite cell becomes `null`, which Nivo paints with `emptyColor` rather
+ * than as a zero.
+ */
+export function matrixToSeries(matrix: ChartMatrix): ChartSeries[] {
+  return matrix.rows.map((row, r) => ({
+    id: row,
+    data: matrix.columns.map((column, c) => {
+      const value = matrix.values[r]?.[c];
+      return { x: column, y: typeof value === "number" && Number.isFinite(value) ? value : null };
+    }),
+  }));
+}
+
 /**
  * Infer the category key and the series keys of a row array the way the
  * webchat renderer did: the first string field is the index, every numeric
@@ -88,6 +111,7 @@ export function treeIdentity(tree: ChartTree): "id" | "name" {
 /** True when there is nothing to draw. */
 export function isEmptyData(data: unknown): boolean {
   if (data == null) return true;
+  if (isMatrix(data)) return data.rows.length === 0 || data.columns.length === 0;
   if (Array.isArray(data)) {
     if (data.length === 0) return true;
     if (isSeriesArray(data)) return data.every((s) => s.data.length === 0);

package/src/components/chart/index.tsx

@@ -41,6 +41,7 @@ export type {
   ChartDataFor,
   ChartDay,
   ChartEngine,
+  ChartMatrix,
   ChartPoint,
   ChartRenderer,
   ChartRow,

package/src/components/chart/nivo-charts.tsx

@@ -2,10 +2,10 @@
 
 import * as React from "react";
 import { useChart } from "./container";
-import { treeIdentity } from "./data";
+import { isMatrix, matrixToSeries, treeIdentity } from "./data";
 import { useNivoTheme } from "./nivo-theme";
 import { chartScales, contrastLabel, resolveVizSeries, useThemeVersion } from "./tokens";
-import type { ChartConfig, ChartDay, ChartRenderer, ChartScale, ChartSeries, ChartTree, ChartType } from "./types";
+import type { ChartConfig, ChartDay, ChartMatrix, ChartRenderer, ChartScale, ChartSeries, ChartTree, ChartType } from "./types";
 
 export type NivoType = Extract<ChartType, "heatmap" | "calendar" | "treemap" | "sunburst">;
 
@@ -94,7 +94,8 @@ export function NivoChart({ type, data, config, renderer, scale, legend, valueFo
   switch (type) {
     case "heatmap": {
       const Component = canvas ? HeatMapCanvas : HeatMapSvg;
-      const rows = data as ChartSeries[];
+      // Either shape lands on Nivo's `[{ id, data: [{ x, y }] }]`.
+      const rows = isMatrix(data) ? matrixToSeries(data as ChartMatrix) : (data as ChartSeries[]);
       // Labels only when cells are big enough to carry them.
       const cells = rows.reduce((n, r) => n + r.data.length, 0);
       const colorConfig =

package/src/components/chart/types.ts

@@ -21,7 +21,10 @@ import type * as React from "react";
  *   (the Nivo line shape the webchat emits). `ChartRow[]` is also accepted.
  * - **pie**, **donut**, **funnel**: `ChartSlice[]` — `[{ id, label?, value }]`.
  * - **scatter** (alias `scatterplot`): `ChartSeries[]` — one series per group.
- * - **heatmap**: `ChartSeries[]` — Nivo heatmap shape, `[{ id: row, data: [{ x: column, y: value }] }]`.
+ * - **heatmap**: `ChartSeries[]` — Nivo heatmap shape, `[{ id: row, data: [{ x: column, y: value }] }]` —
+ *   or `ChartMatrix`, the categorical form a correlation / confusion matrix
+ *   already has: `{ rows, columns, values }` with `values[r][c]` at
+ *   `rows[r] × columns[c]`.
  * - **calendar**: `ChartDay[]` — `[{ day: "2026-01-31", value }]`; `from`/`to`
  *   default to the data's range.
  * - **treemap**, **sunburst**: `ChartTree` — Nivo tree, `{ id, children?: [...], value? }`
@@ -68,6 +71,18 @@ export interface ChartSlice {
   value: number;
 }
 
+/**
+ * A categorical matrix: `values[r][c]` is the cell at `rows[r]` × `columns[c]`.
+ * The shape a correlation matrix, a confusion matrix or a day × hour grid is
+ * already in, so it needs no pivot at the call site. Short rows are padded
+ * with `null` (drawn as the empty colour) rather than treated as zero.
+ */
+export interface ChartMatrix {
+  rows: string[];
+  columns: string[];
+  values: Array<Array<number | null | undefined>>;
+}
+
 /** One day of a calendar heatmap. */
 export interface ChartDay {
   day: string;
@@ -90,7 +105,9 @@ export type ChartDataFor<T extends ChartType> = T extends "bar" | "radar"
     ? ChartSeries[] | ChartRow[]
     : T extends "pie" | "donut" | "funnel"
       ? ChartSlice[]
-      : T extends "scatter" | "scatterplot" | "heatmap"
+      : T extends "heatmap"
+      ? ChartSeries[] | ChartMatrix
+      : T extends "scatter" | "scatterplot"
         ? ChartSeries[]
         : T extends "calendar"
           ? ChartDay[]

package/src/components/data-table/data-table.tsx

@@ -78,6 +78,16 @@ export interface DataTableViewProps<Row extends RowData> {
   /** Error to show above the table, in addition to the server source's. */
   error?: string | Error | null;
   onRowClick?: (row: Row, event: React.MouseEvent<HTMLTableRowElement>) => void;
+  /**
+   * The row a detail pane is currently showing, matched against the row id
+   * (`getRowId`, the row index when that is not set). It gets `data-active`
+   * and the `--ds-primary-soft` tint, independent of checkbox selection — a
+   * master/detail list highlights one row without selecting it, and a table
+   * with both can show a selected set and one open row at once.
+   */
+  activeRowId?: string | null;
+  /** Extra classes per row, e.g. to dim rows the app considers stale. */
+  rowClassName?: (row: Row) => string | undefined;
 }
 
 export type DataTableProps<Row extends RowData> = DataTableViewProps<Row> &
@@ -112,6 +122,8 @@ function DataTableOwned<Row extends RowData>(props: DataTableViewProps<Row> & Us
     loading,
     error,
     onRowClick,
+    activeRowId,
+    rowClassName,
     ...options
   } = props;
   const instance = useDataTable<Row>({
@@ -140,6 +152,8 @@ function DataTableOwned<Row extends RowData>(props: DataTableViewProps<Row> & Us
       loading={loading}
       error={error}
       onRowClick={onRowClick}
+      activeRowId={activeRowId}
+      rowClassName={rowClassName}
     />
   );
 }
@@ -259,6 +273,8 @@ function DataTableView<Row extends RowData>({
   loading,
   error,
   onRowClick,
+  activeRowId,
+  rowClassName,
 }: DataTableViewProps<Row> & { instance: DataTableInstance<Row> }) {
   const { table, paginationMode } = instance;
   const rows = table.getRowModel().rows;
@@ -446,6 +462,7 @@ function DataTableView<Row extends RowData>({
     const endStart = cells.findIndex((cell) => cell.column.getIsPinned() === "end");
     const splitAt = endStart === -1 ? cells.length : endStart;
     const selected = row.getIsSelected();
+    const active = activeRowId != null && row.id === activeRowId;
     const expanded = renderSubComponent && row.getIsExpanded();
 
     const renderCell = (cell: DataTableCell<Row, any>, c: number) => {
@@ -481,7 +498,7 @@ function DataTableView<Row extends RowData>({
             // Pinned cells cover what scrolls under them, so their background is
             // opaque card with the translucent hover / selected tint layered on.
             pin.pinned &&
-              "z-[1] bg-[var(--ds-card)] group-hover/row:bg-[linear-gradient(var(--ds-hover),var(--ds-hover))] group-data-[selected]/row:bg-[linear-gradient(var(--ds-primary-soft),var(--ds-primary-soft))]",
+              "z-[1] bg-[var(--ds-card)] group-hover/row:bg-[linear-gradient(var(--ds-hover),var(--ds-hover))] group-data-[selected]/row:bg-[linear-gradient(var(--ds-primary-soft),var(--ds-primary-soft))] group-data-[active]/row:bg-[linear-gradient(var(--ds-primary-soft),var(--ds-primary-soft))]",
             pin.pinned === "start" && pin.edge && "shadow-[inset_-1px_0_0_var(--ds-border)]",
             pin.pinned === "end" && pin.edge && "shadow-[inset_1px_0_0_var(--ds-border)]",
             !isEditing && "truncate",
@@ -510,6 +527,7 @@ function DataTableView<Row extends RowData>({
           data-slot="data-table-row"
           data-index={virtualIndex}
           data-selected={selected ? "" : undefined}
+          data-active={active ? "" : undefined}
           data-expanded={expanded ? "" : undefined}
           aria-rowindex={index + 2}
           aria-selected={table.options.enableRowSelection ? selected : undefined}
@@ -518,7 +536,11 @@ function DataTableView<Row extends RowData>({
           className={cn(
             "group/row border-b border-[var(--ds-border-subtle)] transition-colors duration-[var(--ds-duration-fast)]",
             "hover:bg-[var(--ds-hover)] data-[selected]:bg-[var(--ds-primary-soft)]",
+            // Independent of selection: a detail pane highlights one row
+            // without ticking its checkbox.
+            "data-[active]:bg-[var(--ds-primary-soft)]",
             onRowClick && "cursor-pointer",
+            rowClassName?.(row.original),
           )}
         >
           {cells.slice(0, splitAt).map((cell, c) => renderCell(cell, c))}