@eifi1/ui-kit 0.7.1 → 0.8.0

package/src/components/skeleton.tsx

@@ -0,0 +1,65 @@
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../lib/cn";
+
+/**
+ * The look of a placeholder, as one class string — the same fill and pulse
+ * `StatTile`'s `loading` headline draws (it imports this), so a tile and the list
+ * beside it shimmer as one surface.
+ *
+ * `motion-reduce:animate-none`: a pulse is motion with no information in it, which
+ * is exactly what `prefers-reduced-motion` asks to be dropped. The fill stays, so the
+ * shape of what is coming is still there.
+ */
+export const SKELETON_CLASS = "animate-pulse rounded bg-[var(--bg-active)] motion-reduce:animate-none";
+
+export type SkeletonShape = "line" | "block" | "circle";
+
+export interface SkeletonProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+  /** `line` (default): a bar the height of a line of small text. `block`: an area
+   *  (an image, a chart, a card body). `circle`: an avatar. Size any of them with
+   *  `className` (`w-32`, `h-40`, `size-8`). */
+  shape?: SkeletonShape;
+  /** For `line`: this many lines, the last one shorter — a paragraph's outline. */
+  lines?: number;
+}
+
+const SHAPE: Record<SkeletonShape, string> = {
+  line: "h-3 w-full",
+  block: "h-24 w-full rounded-md",
+  circle: "size-10 rounded-full",
+};
+
+/**
+ * A grey stand-in for content that is on its way.
+ *
+ * keksdose and kastlan both drew these by hand — `animate-pulse bg-slate-200` in one
+ * place, a token in the next, a pulse that ran under reduced motion everywhere.
+ *
+ * ALWAYS `aria-hidden`. A placeholder is not content, and a reader that met twelve
+ * unnamed grey boxes would have learned nothing. Say "loading" once, where it
+ * belongs: `aria-busy` on the region being filled, or a `Spinner` / sr-only line
+ * beside the skeletons.
+ */
+export function Skeleton({ shape = "line", lines, className, ...rest }: SkeletonProps) {
+  if (shape === "line" && lines !== undefined && lines > 1) {
+    return (
+      <div {...rest} aria-hidden className={cn("flex flex-col gap-2", className)} data-skeleton="lines">
+        {Array.from({ length: lines }, (_, i) => (
+          <div
+            key={i}
+            className={cn(SKELETON_CLASS, SHAPE.line, i === lines - 1 && "w-2/3")}
+            data-skeleton="line"
+          />
+        ))}
+      </div>
+    );
+  }
+  return (
+    <div
+      {...rest}
+      aria-hidden
+      data-skeleton={shape}
+      className={cn(SKELETON_CLASS, SHAPE[shape], className)}
+    />
+  );
+}

package/src/components/stat-tile.tsx

@@ -1,10 +1,15 @@
-import { useId } from "react";
+import { isValidElement, useId, useLayoutEffect, useState } from "react";
 import type { ComponentPropsWithoutRef, CSSProperties, ReactElement, ReactNode } from "react";
 import { ArrowDown, ArrowUp, Minus } from "lucide-react";
 import { cn } from "../lib/cn";
 import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
 import { Card, FieldHint } from "./ui";
 import { Sparkline } from "./sparkline";
+import { Tooltip } from "./tooltip";
+// The kit's one placeholder look, so a loading tile and the Skeleton list beside it
+// shimmer as one surface — and both stop under `prefers-reduced-motion`, which this
+// tile's private copy of the string did not.
+import { SKELETON_CLASS } from "./skeleton";
 
 /**
  * The words a stat tile speaks. The delta's arrow is an icon, and an icon is not a
@@ -94,8 +99,14 @@ export interface StatTileSubValue {
   value: ReactNode;
   /** Defaults to the tile's own `tone`, read per figure (so a `signed` tile shows a
    *  teal September above an amber August). Sub-values are always the muted weight
-   *  of their tone: they are history, and must not outshout the figure above them. */
-  tone?: StatTileTone;
+   *  of their tone: they are history, and must not outshout the figure above them.
+   *
+   *  `"none"` leaves the figure untinted — the row's own muted text, like its label —
+   *  even on a toned tile: keksdose's report KpiCard (reports/charts/kpi-card.tsx),
+   *  whose `negative` convention tints only a figure below zero and leaves the rest
+   *  plain. (`"neutral"` is not that: it is the headline's full text colour, at the
+   *  sub-value's 75 %.) */
+  tone?: StatTileTone | "none";
 }
 
 /** What {@link StatTileProps.renderLink} is handed. Spread it onto your router's
@@ -136,13 +147,61 @@ export interface StatTileProps
   /** Which way is good news. Unset, the delta is stated and not judged (users up and
    *  cost up are the same arrow); set, it is coloured and its sentence says so. */
   goodDirection?: "up" | "down";
-  /** The explanation behind a "?" beside the label (a {@link FieldHint}). */
+  /** The explanation behind a "?" beside the label (a {@link FieldHint}) — hidden
+   *  until asked for, so it is for what a reader MIGHT want to know ("excludes
+   *  transfers between your own accounts"). For a line everyone should read, use
+   *  {@link StatTileProps.description} instead. */
   hint?: string;
-  /** A visible line under the value: "Last 12 months", "3 estates / 9 buildings". */
+  /**
+   * Keep the label to ONE line, cut with an ellipsis, and show the whole of it in a
+   * {@link Tooltip} on hover and focus — but only while it is actually cut, so a
+   * label that fits shows no bubble repeating itself. keksdose's admin MetricTile
+   * wall: twenty tiles whose German labels ("Aktive Abonnements (30 Tage)") wrapped
+   * onto two or three lines and pushed each tile's figure to a different height.
+   *
+   * The label element keeps the FULL text — the ellipsis is paint — so it is still
+   * the tile's accessible name (and the stretched link's, on a link tile) exactly as
+   * without this. Off by default: a wrapping label is what every existing tile does,
+   * and a tile standing alone has room to.
+   *
+   * This is the tooltip: pass the label as a plain STRING rather than wrapping it in
+   * your own `<Tooltip>` for the full text (keksdose's admin metrics-panel.tsx:134
+   * does, from before this prop). A wrapped label shows a bubble even when nothing is
+   * cut, and nests its trigger inside this one's.
+   */
+  truncateLabel?: boolean;
+  /**
+   * The tile's name as plain text, for the places that need a string rather than a
+   * node — today the {@link StatTileProps.trend} sparkline's accessible name. Only
+   * needed when `label` is not a string AND its text cannot be read from it: a label
+   * element's text children are found on their own (a `<Tooltip label="…">Spend
+   * </Tooltip>` label still names its sparkline "Spend"), an icon or a formatted
+   * message component's are not.
+   */
+  name?: string;
+  /** A visible line under the value: "Last 12 months", "3 estates / 9 buildings" —
+   *  always shown, so it is for what every reader needs. An explanation only some
+   *  will want belongs in {@link StatTileProps.hint}, the "?" beside the label. */
   description?: ReactNode;
+  /**
+   * One figure that belongs WITH the headline rather than under it: keksdose's
+   * "Projected €1,850" under a to-date "€420" (KpiCard, feedback #51), which it
+   * currently smuggles into `description` with hand-set margins so the prior-month
+   * sub-values do not come between the two. It is drawn directly under the value
+   * (before the delta, the description and the sparkline) as a sub-value row, with
+   * only a hair of space above it.
+   *
+   * A slot of its own rather than a placement switch for `subValues`: the history
+   * rows (last month, last year) should stay at the bottom where they are, and moving
+   * the whole list up to bring one row with it would put them between the headline
+   * and its delta. Same shape as a sub-value, so the `tone` rules are the same.
+   * Withheld while `loading`, like the sub-values.
+   */
+  projection?: StatTileSubValue;
   subValues?: StatTileSubValue[];
   /** Shorthand for a fluid {@link Sparkline} named after the tile and speaking in
-   *  the tile's number format. */
+   *  the tile's number format. The name is the label's text; see
+   *  {@link StatTileProps.name} for a label that has none. */
   trend?: ReadonlyArray<number | null | undefined>;
   /** A custom sparkline (or any small graphic) in the same place. Wins over `trend`. */
   sparkline?: ReactNode;
@@ -188,7 +247,6 @@ const VALUE_TEXT = {
   sm: "text-xs @[8.5rem]:text-sm @[13rem]:text-base",
 } as const;
 const PADDING = { md: "p-3 sm:p-4", sm: "px-2.5 py-2" } as const;
-const SKELETON = "animate-pulse rounded bg-[var(--bg-active)]";
 
 /**
  * The KPI card: a label, one number, and optionally how it moved, what it is made of
@@ -219,7 +277,10 @@ export function StatTile({
   delta,
   goodDirection,
   hint,
+  truncateLabel = false,
+  name,
   description,
+  projection,
   subValues,
   trend,
   sparkline,
@@ -236,6 +297,8 @@ export function StatTile({
   ...rest
 }: StatTileProps) {
   const text = useKitLabels("statTile", DEFAULT_STAT_TILE_LABELS, labels);
+  const [labelEl, setLabelEl] = useState<HTMLElement | null>(null);
+  const labelCut = useIsTruncated(truncateLabel ? labelEl : null);
   const kitLocale = useKitLocale(locale);
   const id = useId();
   const valueId = `${id}-value`;
@@ -254,7 +317,7 @@ export function StatTile({
 
   const d = typeof delta === "number" ? { value: delta } : delta;
   const hasValue = value !== null && value !== undefined && value !== "";
-  const labelText = typeof label === "string" ? label : undefined;
+  const labelText = name ?? plainText(label);
 
   // ── The label, which is also the link/button when the tile is interactive ──
   const stretched = cn(
@@ -326,7 +389,7 @@ export function StatTile({
   );
   const headline = loading ? (
     <span id={valueId} className="relative block py-0.5">
-      <span aria-hidden className={cn(SKELETON, "block h-6 w-24 max-w-full")} />
+      <span aria-hidden className={cn(SKELETON_CLASS, "block h-6 w-24 max-w-full")} />
       <span className="sr-only">{text.loading}</span>
     </span>
   ) : hasValue ? (
@@ -374,7 +437,19 @@ export function StatTile({
     >
       <div className="flex items-start gap-2">
         <div className="flex min-w-0 flex-1 items-center gap-1 break-words text-xs uppercase tracking-wide text-[var(--text-muted)]">
-          <span className="min-w-0">{labelNode}</span>
+          {truncateLabel && labelCut ? (
+            // Portalled: the tile is `overflow-hidden`, and a bubble inside it would be
+            // clipped by the very box whose edge cut the label.
+            <Tooltip label={label} side="top" portal className="flex min-w-0">
+              <span ref={setLabelEl} className="block min-w-0 truncate">
+                {labelNode}
+              </span>
+            </Tooltip>
+          ) : (
+            <span ref={setLabelEl} className={cn("min-w-0", truncateLabel && "block truncate")}>
+              {labelNode}
+            </span>
+          )}
           {/* Above the stretched link's overlay, so it stays hoverable and focusable. */}
           {hint && <FieldHint label={hint} side="top" className="relative z-10 shrink-0" />}
         </div>
@@ -396,29 +471,21 @@ export function StatTile({
         <div className="mt-1">{headline}</div>
       )}
 
+      {!loading && projection && (
+        <dl className="mt-0.5">
+          <FigureRow figure={projection} tileTone={tone} show={show} priv={priv} />
+        </dl>
+      )}
+
       {deltaNode}
       {description != null && <div className="mt-1 text-xs text-[var(--text-muted)]">{description}</div>}
       {graphic && <div className="mt-2">{graphic}</div>}
 
       {!loading && subValues && subValues.length > 0 && (
         <dl className="mt-1.5 space-y-0.5">
-          {subValues.map((sv, i) => {
-            const svTone = sv.tone ?? (tone === "neutral" ? undefined : tone);
-            return (
-              <div
-                key={i}
-                className="flex flex-wrap items-baseline gap-x-2 text-xs tabular-nums text-[var(--text-muted)]"
-              >
-                <dt className="uppercase tracking-wide">{sv.label}</dt>
-                <dd
-                  data-private={priv}
-                  className={cn("ms-auto whitespace-nowrap", svTone && [toneClass(svTone, sv.value), "opacity-75"])}
-                >
-                  {show(sv.value)}
-                </dd>
-              </div>
-            );
-          })}
+          {subValues.map((sv, i) => (
+            <FigureRow key={i} figure={sv} tileTone={tone} show={show} priv={priv} />
+          ))}
         </dl>
       )}
 
@@ -427,6 +494,72 @@ export function StatTile({
   );
 }
 
+/** One label/value row of a `<dl>`: a sub-value, or the projection. */
+function FigureRow({
+  figure,
+  tileTone,
+  show,
+  priv,
+}: {
+  figure: StatTileSubValue;
+  tileTone: StatTileTone;
+  show: (v: ReactNode) => ReactNode;
+  priv: "" | undefined;
+}) {
+  const own = figure.tone ?? (tileTone === "neutral" ? undefined : tileTone);
+  const svTone = own === "none" ? undefined : own;
+  return (
+    <div className="flex flex-wrap items-baseline gap-x-2 text-xs tabular-nums text-[var(--text-muted)]">
+      <dt className="uppercase tracking-wide">{figure.label}</dt>
+      <dd
+        data-private={priv}
+        className={cn("ms-auto whitespace-nowrap", svTone && [toneClass(svTone, figure.value), "opacity-75"])}
+      >
+        {show(figure.value)}
+      </dd>
+    </div>
+  );
+}
+
+/**
+ * The text of a label node, for the sparkline's name: a string or number as is, an
+ * element by its children, recursively. A `<Tooltip label="…">Spend</Tooltip>` label
+ * yields "Spend" — the text the reader sees, not the bubble's. `undefined` when there
+ * is no text to find (an icon), so the sparkline falls back to its unnamed summary.
+ */
+function plainText(node: ReactNode): string | undefined {
+  const walk = (n: ReactNode): string => {
+    if (typeof n === "string" || typeof n === "number") return String(n);
+    if (Array.isArray(n)) return n.map(walk).join("");
+    if (isValidElement<{ children?: ReactNode }>(n)) return walk(n.props.children);
+    return "";
+  };
+  const text = walk(node).replace(/\s+/g, " ").trim();
+  return text === "" ? undefined : text;
+}
+
+/**
+ * Whether `el`'s text is wider than its box — i.e. whether `truncate` is cutting it.
+ * Re-measured whenever the box resizes (a grid reflowing, a translation loading), not
+ * only on mount. Keyed on the ELEMENT (a callback ref), because wrapping the label in
+ * its tooltip remounts it, and an observer on the old node would watch nothing.
+ */
+function useIsTruncated(el: HTMLElement | null): boolean {
+  const [cut, setCut] = useState(false);
+  useLayoutEffect(() => {
+    // No reset while there is no node: between the unwrapped label unmounting and the
+    // wrapped one mounting there is none, and a reset there would unwrap it again.
+    if (!el) return;
+    const measure = () => setCut(el.scrollWidth > el.clientWidth);
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [el]);
+  return cut;
+}
+
 export interface StatTileGridProps extends ComponentPropsWithoutRef<"div"> {
   /** The narrowest a tile may get before the grid drops a column. The default fits
    *  two tiles on a 320px phone. */

package/src/components/table.tsx

@@ -0,0 +1,263 @@
+import { createContext, useContext, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../lib/cn";
+import { THIN_SCROLLBAR_CLASS, useScrollOverflow } from "./scroll-area";
+
+export type TableDensity = "comfortable" | "compact";
+export type TableAlign = "start" | "center" | "end";
+
+interface TableContextValue {
+  density: TableDensity;
+  zebra: boolean;
+  hover: boolean;
+  captionId: string;
+  registerCaption: () => () => void;
+}
+
+const TableContext = createContext<TableContextValue>({
+  density: "comfortable",
+  zebra: false,
+  hover: false,
+  captionId: "",
+  registerCaption: () => () => {},
+});
+
+/** Which section a row sits in — zebra and hover apply to body rows only. */
+const SectionContext = createContext<"head" | "body" | "foot">("body");
+
+const CELL_PAD: Record<TableDensity, string> = {
+  comfortable: "px-3 py-2",
+  compact: "px-2 py-1",
+};
+
+const ALIGN: Record<TableAlign, string> = {
+  start: "text-start",
+  center: "text-center",
+  end: "text-end",
+};
+
+/**
+ * The alignment a figure column wants: end-aligned (so the units line up under each
+ * other in either reading direction) with tabular digits (so they line up at all).
+ * Exported for a cell the kit did not render — a DataTable column, a `<td>` of the
+ * app's own.
+ */
+export const NUMERIC_CELL_CLASS = "text-end tabular-nums";
+
+export interface TableProps extends ComponentPropsWithoutRef<"table"> {
+  /** `compact` for a dense detail view (a ledger, a spec sheet). */
+  density?: TableDensity;
+  /** Tint every other body row. */
+  zebra?: boolean;
+  /** Tint the body row under the pointer. Off by default: a static table whose rows
+   *  light up promises a click that does nothing. */
+  hover?: boolean;
+  /** Classes for the overflow wrapper around the `<table>` (a max-height, a border). */
+  wrapperClassName?: string;
+}
+
+/**
+ * A plain, static HTML table in the kit's tokens — for the detail views that need
+ * rows and columns and none of {@link DataTable}'s sorting, filtering or paging.
+ *
+ * kastlan renders about twenty of these on shadcn's Table parts; the part names here
+ * are the same idea (`TableHead` is the `<thead>`, `TableHeaderCell` the `<th>`), so
+ * the move is a rename rather than a rewrite.
+ *
+ * The table sits in an overflow-x wrapper, because a table cannot shrink below its
+ * content and on a phone it would otherwise widen the page. While it overflows that
+ * wrapper becomes a tab stop and a `role="region"` named by the `TableCaption` (or the
+ * table's own `aria-label`), so a keyboard user can scroll it and a reader can say
+ * what it is — the same contract as {@link ScrollArea}.
+ *
+ * Alignment is logical throughout (`text-start` / `text-end`), so a right-to-left
+ * page gets its first column on the right without a class changing.
+ */
+export function Table({
+  density = "comfortable",
+  zebra = false,
+  hover = false,
+  wrapperClassName,
+  className,
+  "aria-label": ariaLabel,
+  ...rest
+}: TableProps) {
+  const captionId = useId();
+  const [captions, setCaptions] = useState(0);
+  const wrapper = useRef<HTMLDivElement | null>(null);
+  const overflowing = useScrollOverflow(wrapper);
+
+  const ctx = useMemo<TableContextValue>(
+    () => ({
+      density,
+      zebra,
+      hover,
+      captionId,
+      registerCaption: () => {
+        setCaptions((n) => n + 1);
+        return () => setCaptions((n) => n - 1);
+      },
+    }),
+    [density, zebra, hover, captionId],
+  );
+
+  const regionName = captions > 0 ? { "aria-labelledby": captionId } : ariaLabel ? { "aria-label": ariaLabel } : null;
+
+  return (
+    <TableContext.Provider value={ctx}>
+      <div
+        ref={wrapper}
+        // Only a region when it scrolls AND has a name: a landmark for every short
+        // table on a page would bury the real ones.
+        role={overflowing && regionName ? "region" : undefined}
+        {...(overflowing ? regionName : null)}
+        tabIndex={overflowing ? 0 : undefined}
+        data-overflowing={overflowing || undefined}
+        className={cn(
+          // `relative`: the containing block for an `sr-only` caption.
+          "relative w-full overflow-x-auto",
+          THIN_SCROLLBAR_CLASS,
+          "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-[var(--brand)]",
+          wrapperClassName,
+        )}
+      >
+        <table
+          {...rest}
+          aria-label={ariaLabel}
+          className={cn(
+            "w-full caption-bottom border-collapse text-sm text-[var(--text-primary)]",
+            density === "compact" && "text-xs",
+            className,
+          )}
+        />
+      </div>
+    </TableContext.Provider>
+  );
+}
+
+export type TableHeadProps = ComponentPropsWithoutRef<"thead">;
+
+export function TableHead({ className, ...rest }: TableHeadProps) {
+  return (
+    <SectionContext.Provider value="head">
+      <thead {...rest} className={cn("border-b border-[var(--border)]", className)} />
+    </SectionContext.Provider>
+  );
+}
+
+export type TableBodyProps = ComponentPropsWithoutRef<"tbody">;
+
+export function TableBody({ className, ...rest }: TableBodyProps) {
+  return (
+    <SectionContext.Provider value="body">
+      <tbody {...rest} className={cn("[&>tr:last-child]:border-b-0", className)} />
+    </SectionContext.Provider>
+  );
+}
+
+export type TableFootProps = ComponentPropsWithoutRef<"tfoot">;
+
+/** The totals row. Not in the brief, but every ledger view has one and a `<tfoot>`
+ *  is what tells a reader it is a total rather than one more row. */
+export function TableFoot({ className, ...rest }: TableFootProps) {
+  return (
+    <SectionContext.Provider value="foot">
+      <tfoot {...rest} className={cn("border-t border-[var(--border-strong)] font-medium", className)} />
+    </SectionContext.Provider>
+  );
+}
+
+export type TableRowProps = ComponentPropsWithoutRef<"tr">;
+
+export function TableRow({ className, ...rest }: TableRowProps) {
+  const { zebra, hover } = useContext(TableContext);
+  const section = useContext(SectionContext);
+  const body = section === "body";
+  return (
+    <tr
+      {...rest}
+      className={cn(
+        body && "border-b border-[var(--border)]",
+        body && zebra && "even:bg-[var(--bg-surface-2)]",
+        body && hover && "transition-colors hover:bg-[var(--bg-hover)]",
+        className,
+      )}
+    />
+  );
+}
+
+interface CellAlignProps {
+  /** Shorthand for a figure column: end-aligned, tabular digits. */
+  numeric?: boolean;
+  /** Logical alignment. Default `start` (`end` when `numeric`). */
+  align?: TableAlign;
+}
+
+/** The deprecated HTML `align` attribute is replaced by a logical one. */
+export interface TableHeaderCellProps extends Omit<ComponentPropsWithoutRef<"th">, "align">, CellAlignProps {}
+
+/**
+ * A `<th>`. `scope` defaults to `col` in the head and `row` in the body — a header
+ * cell in a body row is the row's label ("Net rent" in a key-value table), and a
+ * reader needs the scope to read it with each cell beside it.
+ */
+export function TableHeaderCell({ numeric = false, align, scope, className, ...rest }: TableHeaderCellProps) {
+  const { density } = useContext(TableContext);
+  const section = useContext(SectionContext);
+  return (
+    <th
+      {...rest}
+      scope={scope ?? (section === "head" ? "col" : "row")}
+      className={cn(
+        CELL_PAD[density],
+        ALIGN[align ?? (numeric ? "end" : "start")],
+        numeric && "tabular-nums",
+        "align-bottom font-medium",
+        section === "head" ? "text-xs text-[var(--text-muted)]" : "align-top text-[var(--text-secondary)]",
+        className,
+      )}
+    />
+  );
+}
+
+export interface TableCellProps extends Omit<ComponentPropsWithoutRef<"td">, "align">, CellAlignProps {}
+
+export function TableCell({ numeric = false, align, className, ...rest }: TableCellProps) {
+  const { density } = useContext(TableContext);
+  return (
+    <td
+      {...rest}
+      className={cn(
+        CELL_PAD[density],
+        "align-top",
+        ALIGN[align ?? (numeric ? "end" : "start")],
+        numeric && "tabular-nums whitespace-nowrap",
+        className,
+      )}
+    />
+  );
+}
+
+export type TableCaptionProps = ComponentPropsWithoutRef<"caption">;
+
+/**
+ * The table's title. Beneath the table by default (`caption-bottom`, the shadcn
+ * convention kastlan's views already follow); `className="caption-top"` moves it.
+ * `className="sr-only"` keeps it for readers only — the wrapper is `relative`, so
+ * the hidden caption stays inside it.
+ *
+ * It also names the scroll region when the table overflows: it registers itself
+ * with the {@link Table} so the wrapper points at an id that exists, and never at
+ * one that does not.
+ */
+export function TableCaption({ className, id, ...rest }: TableCaptionProps) {
+  const { captionId, registerCaption } = useContext(TableContext);
+  useLayoutEffect(() => (id ? undefined : registerCaption()), [id, registerCaption]);
+  return (
+    <caption
+      {...rest}
+      id={id ?? captionId}
+      className={cn("mt-2 text-start text-sm text-[var(--text-muted)]", className)}
+    />
+  );
+}

package/src/components/toggle-legend.tsx

@@ -73,8 +73,9 @@ export interface LegendEntry {
   marker?: "swatch" | "stroke";
   /** Which of {@link STROKE_PATTERNS}, when the marker is a stroke — the same index
    *  `SeriesChartSeries.dash` takes, so a legend cannot promise a dot-dash the plot
-   *  draws dashed. */
-  dash?: number;
+   *  draws dashed. Or the same custom `stroke-dasharray` string the series draws with
+   *  (keksdose's `"4 3"`). */
+  dash?: number | string;
 }
 
 export interface ToggleLegendProps {
@@ -214,7 +215,7 @@ function LegendMark({ entry, off }: { entry: LegendEntry; off: boolean }) {
           y2={1}
           stroke={entry.color}
           strokeWidth={2}
-          strokeDasharray={strokeDash(entry.dash ?? 0)}
+          strokeDasharray={typeof entry.dash === "string" ? entry.dash : strokeDash(entry.dash ?? 0)}
         />
       </svg>
     );