cortena-ui 1.2.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortena-ui",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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": {
@@ -39,11 +39,11 @@
     "prepack": "pnpm build"
   },
   "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
     "cortena-design": ">=3.2.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "zod": "^3.25.0 || ^4.0.0",
-    "@tanstack/react-query": "^5.0.0"
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "dependencies": {
     "@base-ui/react": "^1.8.0",
@@ -89,6 +89,7 @@
     "playwright": "^1.63.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "rehype-raw": "^7.0.0",
     "tailwindcss": "^4.3.3",
     "tsdown": "^0.23.0",
     "typescript": "^5.9.0",
@@ -99,13 +100,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "peerDependenciesMeta": {
-    "zod": {
-      "optional": true
-    },
-    "@tanstack/react-query": {
-      "optional": true
-    }
   }
 }

package/src/a2ui/catalogue.ts

@@ -119,6 +119,15 @@ const buttonVariant = z
 
 const buttonSize = z.enum(["sm", "md", "lg"]).describe("Control size.");
 
+/**
+ * Root-relative means one slash and then a path. `//evil.example/x` is
+ * protocol-relative — the browser resolves it against the page's scheme and
+ * goes off-origin — and `/\evil.example` is the same trick, because browsers
+ * treat a backslash after the leading slash as a second slash.
+ */
+const rootRelative = (value: string) =>
+  value.startsWith("/") && value[1] !== "/" && value[1] !== "\\";
+
 /**
  * A URL an agent may point at.
  *
@@ -129,7 +138,7 @@ const buttonSize = z.enum(["sm", "md", "lg"]).describe("Control size.");
 const httpUrl = z
   .string()
   .refine(
-    (value) => /^https?:\/\//i.test(value) || value.startsWith("/") || value.startsWith("#"),
+    (value) => /^https?:\/\//i.test(value) || rootRelative(value) || value.startsWith("#"),
     "Must be an http(s), root-relative or fragment URL.",
   )
   .describe("Destination URL (http, https, root-relative or fragment).");
@@ -137,7 +146,7 @@ const httpUrl = z
 const imageUrl = z
   .string()
   .refine(
-    (value) => /^https?:\/\//i.test(value) || /^data:image\//i.test(value) || value.startsWith("/"),
+    (value) => /^https?:\/\//i.test(value) || /^data:image\//i.test(value) || rootRelative(value),
     "Must be an http(s), root-relative or data:image URL.",
   )
   .describe("Image URL (http, https, root-relative or data:image).");

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 { NivoChart, type NivoType } from "./nivo-charts";
+import { configFor, isEmptyData, isMatrix, isSeriesArray, toRows, toSlices } from "./data";
+import { NivoChart, resetNivoChunks, 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":
@@ -79,16 +82,34 @@ function seriesKeys(type: ChartType, data: unknown, indexBy?: string, keys?: str
   }
 }
 
-class ChunkBoundary extends React.Component<
-  { children: React.ReactNode; fallback: React.ReactNode },
-  { failed: boolean }
-> {
-  state = { failed: false };
+interface ChunkBoundaryProps {
+  children: React.ReactNode;
+  /** Changing it clears a previous failure and renders the children again. */
+  resetKey: string;
+  fallback: (retry: () => void) => React.ReactNode;
+}
+
+/**
+ * Catches a Nivo chunk that failed to load. Recovering takes two things,
+ * because `React.lazy` memoises a rejection for the life of the page: fresh
+ * lazy components ({@link resetNivoChunks}) and a boundary that leaves its
+ * failed state. `resetKey` does the second on its own when the chart changes,
+ * and the fallback gets a `retry` that does both.
+ */
+class ChunkBoundary extends React.Component<ChunkBoundaryProps, { failed: boolean; key: string }> {
+  state = { failed: false, key: this.props.resetKey };
   static getDerivedStateFromError() {
     return { failed: true };
   }
+  static getDerivedStateFromProps(props: ChunkBoundaryProps, state: { failed: boolean; key: string }) {
+    return props.resetKey === state.key ? null : { failed: false, key: props.resetKey };
+  }
+  retry = () => {
+    resetNivoChunks();
+    this.setState({ failed: false });
+  };
   render() {
-    return this.state.failed ? this.props.fallback : this.props.children;
+    return this.state.failed ? this.props.fallback(this.retry) : this.props.children;
   }
 }
 
@@ -101,6 +122,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,
@@ -140,7 +169,22 @@ function Chart<T extends ChartType>({
   else if (empty) body = <ChartEmpty>{emptyMessage}</ChartEmpty>;
   else if (engine === "nivo") {
     body = (
-      <ChunkBoundary fallback={<ChartError>Chart could not be loaded</ChartError>}>
+      <ChunkBoundary
+        resetKey={`${type}|${renderer}`}
+        fallback={(retry) => (
+          <ChartError>
+            Chart could not be loaded.{" "}
+            <button
+              type="button"
+              data-slot="chart-retry"
+              onClick={retry}
+              className="underline underline-offset-2"
+            >
+              Retry
+            </button>
+          </ChartError>
+        )}
+      >
         <React.Suspense fallback={<ChartLoading />}>
           <NivoChart
             type={type as NivoType}

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,