@eifi1/ui-kit 0.8.1 → 0.10.0

package/src/components/series-chart.tsx

@@ -26,8 +26,8 @@
 // "category"`) or real dates (`x.type: "time"`) instead of a number the app had to
 // invent. What each of those does to the zoom is decided in one place,
 // `defaultZoomAxes` in `chart-zoom.tsx`.
-import { useMemo } from "react";
-import type { ReactNode, RefObject } from "react";
+import { useMemo, useRef, useState } from "react";
+import type { KeyboardEvent, ReactNode, RefObject } from "react";
 import {
   Area,
   Bar,
@@ -37,8 +37,12 @@ import {
   Line,
   ReferenceDot,
   ReferenceLine,
+  Rectangle,
   XAxis,
   YAxis,
+  usePlotArea,
+  useXAxisScale,
+  type BarShapeProps,
 } from "recharts";
 import { ChartContainer, ChartTooltip, ChartTooltipContent, type ChartConfig } from "./chart";
 import {
@@ -202,6 +206,22 @@ interface SeriesChartAxisShape {
    * a hairline). A pinned `domain` is left alone either way.
    */
   includeZero?: boolean;
+  /**
+   * Tick only on whole numbers — the y counterpart of `SeriesChartX.integerTicks`, and
+   * what keksdose's user-count axis (`metrics-panel.tsx`, `wholeTicks`) and its runway
+   * in days (`cash-buffer-chart.tsx`, `wholeDayTicks`) each wrote by hand: a band of
+   * [0, 3.1] users is ticked 0 1 2 3, not 0 0.5 1 … 3, and a short runway is not ticked
+   * 0 / 0.5 / 1 under a rounding formatter that prints "1" twice. A (zoom) window that
+   * holds no whole number falls back to the ordinary ticks rather than to none.
+   *
+   * AUTOMATIC by default — on when every value this axis carries is a whole number
+   * (counts), because that is where a half tick is a value no sample can have, and it
+   * changes nothing on a span wider than about eight, which already ticks on whole
+   * steps. `true` forces it over fractional data (days of runway computed as 43.7);
+   * `false` keeps fractional ticks for a continuous quantity that merely happens to be
+   * whole in this sample. `tickValues` wins over either.
+   */
+  integerTicks?: boolean;
 }
 
 /**
@@ -818,6 +838,150 @@ const STEP_WIDTH = 1.5;
  *  which recharts cannot tell apart per cell, so stacks stay square. */
 const BAR_RADIUS: [number, number, number, number] = [3, 3, 0, 0];
 
+/**
+ * One keyboard stop of a clickable chart: a bar, or (a chart with no bars) a whole slot.
+ * `from`/`to` bound its slot on the plotted number line — half way to each neighbour,
+ * or to the edge of the window on show.
+ */
+interface PointStop {
+  index: number;
+  /** The bar's series; absent for a slot. */
+  key?: string;
+  from: number;
+  to: number;
+  /** The accessible name: where it is and what it says. */
+  name: string;
+}
+
+/**
+ * The shape of a series whose bar has keyboard focus: recharts' own rectangle, with an
+ * outline on the one bar at `index` — drawn at the bar's exact geometry, which an
+ * overlay could only guess at. Not `activeBar`: that follows the tooltip's active index,
+ * which recharts stops taking from `defaultIndex` once a pointer has hovered the chart.
+ */
+function focusedBarShape(index: number) {
+  return function FocusedBar(props: BarShapeProps) {
+    const focused = props.originalDataIndex === index;
+    return (
+      <Rectangle {...props} {...(focused ? { stroke: "var(--text-primary)", strokeWidth: 2 } : {})} />
+    );
+  };
+}
+
+/**
+ * The keyboard's way onto a clickable chart (`onPointClick`): one focusable `<rect>` per
+ * bar, or per slot when there are no bars, laid over the plot INSIDE the recharts chart,
+ * where the x scale answers.
+ *
+ * keksdose drew its weekday pattern as seven real `<button>`s (spending-tab.tsx) because
+ * a recharts bar is reachable by nothing but the pointer. This is that, for every chart:
+ *
+ * - ONE tab stop (roving `tabIndex`): Tab moves past the chart, not through 30 bars.
+ * - ←/→ step through the stops in order, ↑/↓ between the bars of one slot, Home/End.
+ * - ↵ and Space report the stop as a click would — with the series for a bar.
+ * - Each is a `role="button"` named "period — series: value".
+ *
+ * The stops take NO pointer events, so the drag-to-zoom layer, the tooltip and the
+ * pointer's own clicks underneath behave exactly as they did. Focus is shown by the
+ * slot tinted and, for a bar, its own outline (`focusedBarShape`) — and by the tooltip,
+ * moved to the stop through `defaultIndex`, which recharts honours until a pointer has
+ * hovered the chart.
+ */
+function PointKeys({
+  stops,
+  current,
+  label,
+  onFocusStop,
+  onBlurStops,
+  onPick,
+}: {
+  stops: readonly PointStop[];
+  current: number;
+  label: string;
+  onFocusStop: (at: number) => void;
+  onBlurStops: () => void;
+  onPick: (stop: PointStop) => void;
+}) {
+  const plot = usePlotArea();
+  const scale = useXAxisScale();
+  const refs = useRef<(SVGRectElement | null)[]>([]);
+  if (!plot || !scale || plot.width <= 0 || plot.height <= 0) return null;
+
+  const move = (at: number) => {
+    const next = Math.max(0, Math.min(stops.length - 1, at));
+    refs.current[next]?.focus();
+  };
+  const onKeyDown = (at: number) => (event: KeyboardEvent<SVGRectElement>) => {
+    const stop = stops[at];
+    // ↑/↓ stay in the slot: the next or previous bar of the same period. The stops are
+    // in slot order, so a slot's bars are neighbours.
+    const inSlot = (step: 1 | -1) => (stops[at + step]?.index === stop.index ? at + step : at);
+    const target =
+      event.key === "ArrowRight"
+        ? at + 1
+        : event.key === "ArrowLeft"
+          ? at - 1
+          : event.key === "ArrowDown"
+            ? inSlot(1)
+            : event.key === "ArrowUp"
+              ? inSlot(-1)
+              : event.key === "Home"
+                ? 0
+                : event.key === "End"
+                  ? stops.length - 1
+                  : undefined;
+    if (target !== undefined) {
+      event.preventDefault();
+      move(target);
+    } else if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      onPick(stop);
+    }
+  };
+
+  const left = plot.x;
+  const right = plot.x + plot.width;
+  return (
+    <g role="group" aria-label={label}>
+      {stops.map((stop, at) => {
+        // An edge with no neighbour runs to the plot's edge.
+        const a = finite(scale(stop.from)) ?? left;
+        const b = finite(scale(stop.to)) ?? right;
+        const x0 = Math.max(left, Math.min(a, b));
+        const x1 = Math.min(right, Math.max(a, b));
+        return (
+          <rect
+            key={`${stop.index}:${stop.key ?? ""}`}
+            ref={(node) => {
+              refs.current[at] = node;
+            }}
+            role="button"
+            tabIndex={at === current ? 0 : -1}
+            aria-label={stop.name}
+            data-point-key={stop.key}
+            x={x0}
+            y={plot.y}
+            width={Math.max(0, x1 - x0)}
+            height={plot.height}
+            fill="transparent"
+            // Focus only: the pointer's drag, hover and click belong to what is below.
+            pointerEvents="none"
+            strokeWidth={2}
+            className={cn(
+              "outline-none focus-visible:fill-[var(--brand)]/10",
+              // A bar outlines ITSELF (see `FOCUSED_BAR`); a slot has nothing else to.
+              stop.key === undefined && "focus-visible:stroke-[var(--brand)]",
+            )}
+            onFocus={() => onFocusStop(at)}
+            onBlur={onBlurStops}
+            onKeyDown={onKeyDown(at)}
+          />
+        );
+      })}
+    </g>
+  );
+}
+
 interface PlotProps extends Omit<SeriesChartProps, "rows" | "x"> {
   /** The rows AS PLOTTED — what the zoom fits on. The caller's are `model.source`. */
   rows: readonly SeriesChartRow[];
@@ -851,6 +1015,10 @@ function SeriesPlot({
   const labels = useKitLabels("seriesChart", DEFAULT_SERIES_CHART_LABELS, labelsProp);
   const locale = useKitLocale(localeProp);
   const number = useDefaultFormat(localeProp);
+  // The keyboard stops' roving tab stop, and the one that has focus (see `PointKeys`).
+  // Up here, above the empty state's early return, like every hook.
+  const [keyStop, setKeyStop] = useState(0);
+  const [keyFocus, setKeyFocus] = useState<number | undefined>(undefined);
 
   // A number is pixels, set inline; a string is a class. Either way the one value
   // sizes both the chart and its empty state.
@@ -995,6 +1163,19 @@ function SeriesPlot({
     series.some(
       (entry) => (entry.axis ?? DEFAULT_Y_AXIS) === axis.id && (entry.type ?? "line") !== "line",
     );
+  // Whole-number ticks on an axis whose values are all whole — see
+  // `SeriesChartAxis.integerTicks`. A stack of whole layers sums to a whole number, so
+  // the layers are enough to look at.
+  const wholeOnly = (axis: SeriesChartAxis) =>
+    axis.integerTicks ??
+    series
+      .filter((entry) => (entry.axis ?? DEFAULT_Y_AXIS) === axis.id)
+      .every((entry) =>
+        plotted.every((row) => {
+          const value = finite(row[entry.key]);
+          return value === undefined || Number.isInteger(value);
+        }),
+      );
   const onAxis = (axisId: string) => (ref: { axis?: string }) => (ref.axis ?? DEFAULT_Y_AXIS) === axisId;
   const fittedY = (axis: SeriesChartAxis): [number, number] | undefined => {
     const own = [
@@ -1024,6 +1205,48 @@ function SeriesPlot({
     return row ? { index, row, x: xOf(index), key } : undefined;
   };
 
+  // The keyboard stops of a clickable chart — every bar with a value, slot by slot; or,
+  // with no bars, every slot with any value. Only what is inside the window on show.
+  const stops: PointStop[] = [];
+  if (onPointClick) {
+    const valueText = valueFormat ?? number;
+    const nameOf = (entry: SeriesChartSeries) =>
+      typeof entry.label === "string" || typeof entry.label === "number" ? String(entry.label) : entry.key;
+    const said = (entry: SeriesChartSeries, value: number) => {
+      const name = nameOf(entry);
+      return name ? `${name}: ${valueText(value)}` : valueText(value);
+    };
+    const bars = series.filter((entry) => entry.type === "bar");
+    const [low, high] = fittedX ?? [-Infinity, Infinity];
+    const placed = plotted
+      .map((row, index) => ({ index, at: model.kind === "category" ? index : finite(row[xKey]) }))
+      .filter((slot): slot is { index: number; at: number } => slot.at !== undefined && slot.at >= low && slot.at <= high)
+      .sort((a, b) => a.at - b.at);
+    placed.forEach(({ index, at }, k) => {
+      const from = k > 0 ? (placed[k - 1].at + at) / 2 : low;
+      const to = k < placed.length - 1 ? (placed[k + 1].at + at) / 2 : high;
+      // The heading the tooltip would give it, when that is text; else the tick.
+      const heading = xLabel(at);
+      const where = typeof heading === "string" && heading ? heading : xFormat(at);
+      const valued = (bars.length ? bars : series)
+        .map((entry) => ({ entry, value: finite(rows[index]?.[entry.key]) }))
+        .filter((cell): cell is { entry: SeriesChartSeries; value: number } => cell.value !== undefined);
+      if (bars.length) {
+        for (const { entry, value } of valued) {
+          stops.push({ index, key: entry.key, from, to, name: `${where} — ${said(entry, value)}` });
+        }
+      } else if (valued.length) {
+        stops.push({
+          index,
+          from,
+          to,
+          name: `${where} — ${valued.map(({ entry, value }) => said(entry, value)).join(", ")}`,
+        });
+      }
+    });
+  }
+  const focusedStop = keyFocus === undefined ? undefined : stops[keyFocus];
+
   const dotFor = (entry: SeriesChartSeries) => {
     const want = entry.dot;
     if (!want) return false;
@@ -1080,6 +1303,9 @@ function SeriesPlot({
         // Positive and negative layers stacked apart, as `axisExtent` fits them — a
         // month's expenses hang below the axis instead of eating into its income.
         stackOffset="sign"
+        // recharts' own keyboard layer makes the whole surface a tab stop whose arrows
+        // move the tooltip — a second stop beside `PointKeys`, and one ↵ does nothing on.
+        accessibilityLayer={!onPointClick}
         onClick={
           onPointClick
             ? (state) => {
@@ -1136,7 +1362,10 @@ function SeriesPlot({
               yAxisId={axis.id}
               hide={axis.hide}
               domain={domain}
-              ticks={resolveTicks(axis.tickValues, domain, finite) ?? niceTicks(domain)}
+              ticks={
+                resolveTicks(axis.tickValues, domain, finite) ??
+                (wholeOnly(axis) ? (integerTicks(domain) ?? niceTicks(domain)) : niceTicks(domain))
+              }
               allowDataOverflow={zoomed}
               orientation={axis.orientation ?? "left"}
               width={axisBandWidth(axis.width, Boolean(axis.title) && !axis.hide)}
@@ -1170,6 +1399,8 @@ function SeriesPlot({
           // The content shifts itself 12 px off the cursor (or flips) against the
           // boundary; recharts' own offset on top would double it.
           {...(tooltip?.boundary ? { offset: 0 } : {})}
+          // The keyboard's stop shows its tooltip as the pointer's would.
+          defaultIndex={focusedStop?.index}
           content={
             <ChartTooltipContent
               labelFormatter={(value) => xLabel(Number(value))}
@@ -1196,6 +1427,9 @@ function SeriesPlot({
                 fill={color}
                 fillOpacity={entry.fillOpacity}
                 radius={entry.stack === undefined ? BAR_RADIUS : 0}
+                // Only the focused stop's series swaps its shape, and only for as long
+                // as it has focus: every other bar keeps recharts' own.
+                {...(focusedStop?.key === entry.key ? { shape: focusedBarShape(focusedStop.index) } : {})}
                 onClick={
                   onPointClick
                     ? (_bar, index, event) => {
@@ -1320,6 +1554,22 @@ function SeriesPlot({
             />
           );
         })}
+        {stops.length > 0 && (
+          <PointKeys
+            stops={stops}
+            current={Math.min(keyStop, stops.length - 1)}
+            label={labels.points}
+            onFocusStop={(at) => {
+              setKeyStop(at);
+              setKeyFocus(at);
+            }}
+            onBlurStops={() => setKeyFocus(undefined)}
+            onPick={(stop) => {
+              const hit = hitAt(stop.index, stop.key);
+              if (hit) onPointClick?.(hit);
+            }}
+          />
+        )}
         {zoom?.layer}
       </ComposedChart>
     </ChartContainer>

package/src/components/status-dot.tsx

@@ -0,0 +1,99 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import type { ProgressBarTone } from "./progress-bar";
+
+/**
+ * The tones are `ProgressBar`'s, name for name — which are `Chip`'s, less nothing — so a
+ * dot in a legend, the bar it explains and the badge beside it can be given the same
+ * word and agree. The money pair is here for the same reason it is there: a legend
+ * swatch for income is money, not "success".
+ */
+export type StatusDotTone = ProgressBarTone;
+
+/** `sm` 8px (keksdose's unread dot on the support trigger), `md` 10px (the avatar's
+ *  unread dot), `lg` 12px (kastlan's occupancy legend swatch). */
+export type StatusDotSize = "sm" | "md" | "lg";
+
+const FILL: Record<StatusDotTone, string> = {
+  brand: "bg-[var(--brand)]",
+  neutral: "bg-[var(--text-muted)]",
+  success: "bg-[var(--success)]",
+  warning: "bg-[var(--warning)]",
+  danger: "bg-[var(--danger)]",
+  info: "bg-[var(--info)]",
+  income: "bg-[var(--money-income)]",
+  expense: "bg-[var(--money-expense)]",
+};
+
+const SIZE: Record<StatusDotSize, string> = { sm: "size-2", md: "size-2.5", lg: "size-3" };
+
+export interface StatusDotProps extends Omit<ComponentPropsWithoutRef<"span">, "children"> {
+  tone?: StatusDotTone;
+  size?: StatusDotSize;
+  /**
+   * Visible text beside the dot — a legend entry ("Rented") or a status ("Online"). It
+   * is also what a screen reader reads: the dot itself is decorative whenever there is
+   * a label.
+   *
+   * Without a label the dot is hidden from assistive technology, because a coloured
+   * circle says nothing to someone who cannot see it. Say the state where it IS read —
+   * keksdose's avatar trigger puts "3 unread" in its own `aria-label` — or give the dot
+   * an `aria-label` of its own, which makes it an image with that name.
+   */
+  label?: ReactNode;
+  /**
+   * A ring in the surface colour round the dot, so a dot laid over the corner of an
+   * icon or an avatar reads as a separate mark and not a smudge (keksdose top-bar.tsx
+   * :152, account-menu.tsx ~385, both hand-drawing `ring-2 ring-white
+   * dark:ring-slate-900`). Position it with `className` (`absolute -end-0.5 -top-0.5`).
+   */
+  ring?: boolean;
+  /** Extra classes for the dot itself; `className` goes on the outer element. */
+  dotClassName?: string;
+}
+
+/**
+ * A small token-coloured dot, with an optional label.
+ *
+ * kastlan's reporting dashboard (dashboard-tab.tsx:79) paints its occupancy legend
+ * with raw `bg-green-500` / `bg-red-500` / `bg-yellow-500`, which ignores the palette
+ * and the dark theme; keksdose draws two unread dots by hand in `rose-500`. Both are
+ * this.
+ */
+export function StatusDot({
+  tone = "neutral",
+  size = "sm",
+  label,
+  ring = false,
+  className,
+  dotClassName,
+  "aria-label": ariaLabel,
+  ...rest
+}: StatusDotProps) {
+  const dot = (
+    <span
+      className={cn(
+        "inline-block shrink-0 rounded-full",
+        SIZE[size],
+        FILL[tone],
+        ring && "ring-2 ring-[var(--bg-surface)]",
+        label == null && className,
+        dotClassName,
+      )}
+      {...(label == null
+        ? ariaLabel
+          ? { role: "img", "aria-label": ariaLabel, ...rest }
+          : { "aria-hidden": true, ...rest }
+        : { "aria-hidden": true })}
+    />
+  );
+  if (label == null) return dot;
+  return (
+    // No `aria-label` here: the visible label is the text, and a name on a role-less
+    // span is one ARIA forbids and screen readers ignore.
+    <span {...rest} className={cn("inline-flex min-w-0 items-center gap-1.5 text-sm", className)}>
+      {dot}
+      <span className="min-w-0 truncate">{label}</span>
+    </span>
+  );
+}

package/src/components/table.tsx

@@ -1,9 +1,17 @@
-import { createContext, useContext, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
-import type { ComponentPropsWithoutRef } from "react";
+import { Children, createContext, useContext, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { THIN_SCROLLBAR_CLASS, useScrollOverflow } from "./scroll-area";
 
-export type TableDensity = "comfortable" | "compact";
+/** `none` (0.10.0): no cell padding at all — keksdose's VAT summary, a table set
+ *  inside a card's own padding whose columns are spaced by hand (`pl-2` on exactly the
+ *  columns that need it). Type stays at the body size, as `comfortable`. */
+export type TableDensity = "comfortable" | "compact" | "none";
+/** CSS `table-layout`. `auto` (the browser default) sizes columns to their content;
+ *  `fixed` takes widths from the first row and ignores the rest — keksdose's VAT
+ *  summary switches to it while editing so two inputs stop bidding against the
+ *  figures for room. */
+export type TableLayout = "auto" | "fixed";
 export type TableAlign = "start" | "center" | "end";
 
 interface TableContextValue {
@@ -28,6 +36,7 @@ const SectionContext = createContext<"head" | "body" | "foot">("body");
 const CELL_PAD: Record<TableDensity, string> = {
   comfortable: "px-3 py-2",
   compact: "px-2 py-1",
+  none: "p-0",
 };
 
 const ALIGN: Record<TableAlign, string> = {
@@ -54,6 +63,8 @@ export interface TableProps extends ComponentPropsWithoutRef<"table"> {
   hover?: boolean;
   /** Classes for the overflow wrapper around the `<table>` (a max-height, a border). */
   wrapperClassName?: string;
+  /** See {@link TableLayout}. Unset leaves the browser's `auto` and adds no class. */
+  layout?: TableLayout;
 }
 
 /**
@@ -78,6 +89,7 @@ export function Table({
   zebra = false,
   hover = false,
   wrapperClassName,
+  layout,
   className,
   "aria-label": ariaLabel,
   ...rest
@@ -127,6 +139,8 @@ export function Table({
           className={cn(
             "w-full caption-bottom border-collapse text-sm text-[var(--text-primary)]",
             density === "compact" && "text-xs",
+            layout === "fixed" && "table-fixed",
+            layout === "auto" && "table-auto",
             className,
           )}
         />
@@ -145,16 +159,87 @@ export function TableHead({ className, ...rest }: TableHeadProps) {
   );
 }
 
-export type TableBodyProps = ComponentPropsWithoutRef<"tbody">;
+export interface TableBodyProps extends ComponentPropsWithoutRef<"tbody"> {
+  /**
+   * Shown as ONE full-width row (a {@link TableEmpty}) when the body has no rows —
+   * `children` that render nothing: an empty `.map`, a `false`, `null`. kastlan hand-
+   * writes that row with a counted `colSpan` in unit-values-editor, the meeting agenda
+   * and invitations tabs, the journal-entry and invoice detail pages, and a column
+   * added later leaves every one of those counts one short.
+   */
+  empty?: ReactNode;
+}
 
-export function TableBody({ className, ...rest }: TableBodyProps) {
+export function TableBody({ className, empty, children, ...rest }: TableBodyProps) {
+  // `toArray` drops null/undefined/booleans and flattens arrays, so `[[], false]` —
+  // an empty map beside a conditional row that is off — is no rows.
+  const hasRows = Children.toArray(children).length > 0;
   return (
     <SectionContext.Provider value="body">
-      <tbody {...rest} className={cn("[&>tr:last-child]:border-b-0", className)} />
+      <tbody {...rest} className={cn("[&>tr:last-child]:border-b-0", className)}>
+        {hasRows || empty === undefined || empty === null || empty === false ? (
+          children
+        ) : (
+          <TableEmpty>{empty}</TableEmpty>
+        )}
+      </tbody>
     </SectionContext.Provider>
   );
 }
 
+export interface TableEmptyProps extends Omit<ComponentPropsWithoutRef<"tr">, "children"> {
+  children: ReactNode;
+  /** Columns to span. Default: MEASURED — the widest row of the table it renders in,
+   *  counted after mount, so the row stays full width when a column is added. */
+  colSpan?: number;
+  /** Classes for the `<td>`. */
+  cellClassName?: string;
+}
+
+/**
+ * The "nothing here" row: one cell across every column, centred, muted. What
+ * {@link TableBodyProps.empty} renders, and usable on its own for a body whose rows
+ * are not its direct children.
+ */
+export function TableEmpty({ children, colSpan, cellClassName, className, ...rest }: TableEmptyProps) {
+  const { density } = useContext(TableContext);
+  const cell = useRef<HTMLTableCellElement | null>(null);
+  const [measured, setMeasured] = useState(1);
+  // Every render, deliberately: a column can appear in the head without anything this
+  // row depends on changing. It cannot loop — setting the same count is a bail-out.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useLayoutEffect(() => {
+    if (colSpan !== undefined) return;
+    const row = cell.current?.parentElement;
+    const table = cell.current?.closest("table");
+    if (!row || !table) return;
+    let widest = 1;
+    for (const r of Array.from(table.rows)) {
+      if (r === row) continue;
+      let n = 0;
+      for (const c of Array.from(r.cells)) n += c.colSpan || 1;
+      widest = Math.max(widest, n);
+    }
+    setMeasured(widest);
+  });
+  return (
+    <tr {...rest} data-table-empty="" className={className}>
+      <td
+        ref={cell}
+        colSpan={colSpan ?? measured}
+        className={cn(
+          // `none` keeps the message off the edges regardless: it is text, not a figure.
+          density === "none" ? "py-2" : CELL_PAD[density],
+          "text-center text-[var(--text-muted)]",
+          cellClassName,
+        )}
+      >
+        {children}
+      </td>
+    </tr>
+  );
+}
+
 export type TableFootProps = ComponentPropsWithoutRef<"tfoot">;
 
 /** The totals row. Not in the brief, but every ledger view has one and a `<tfoot>`

package/src/components/text.tsx

@@ -0,0 +1,89 @@
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+/* ── SectionLabel ─────────────────────────────────────────────────────────── */
+
+/**
+ * `xs` is 10px — the size `LegendGroup`'s title and the top-bar menus' heading row draw;
+ * `sm` (default) is 12px — the size `StatTile`'s label and lenkbank's section headings
+ * (control-page.tsx:119/123/127) draw. Two sizes because the label sits either inside a
+ * dense panel (a legend, a menu) or above a block of page content, and one size looked
+ * wrong in the other place.
+ */
+export type SectionLabelSize = "xs" | "sm";
+
+/**
+ * The small, uppercase, tracked, muted label — as a class string, per size.
+ *
+ * Exported because `LegendGroup` and `StatTile` already draw it inline, and a class a
+ * caller has to position itself (a `<th>`, a `<legend>`, a menu `<li>`) is better
+ * reached as a string than wrapped in a component that only takes a `className`. The
+ * uppercase is CSS, so a screen reader reads the text as written: write it in normal
+ * case.
+ */
+export const SECTION_LABEL_CLASS: Record<SectionLabelSize, string> = {
+  xs: "text-[10px] font-semibold uppercase tracking-wide text-[var(--text-muted)]",
+  sm: "text-xs font-semibold uppercase tracking-wide text-[var(--text-muted)]",
+};
+
+type SectionLabelElement = "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span" | "div" | "legend";
+
+export interface SectionLabelProps extends ComponentPropsWithoutRef<"h3"> {
+  /**
+   * The element — which is the heading LEVEL, and so is the caller's to pick: the kit
+   * cannot know where in the outline the label sits. Default `h3`, which is what
+   * lenkbank's control page writes under its `h2` card title. Pass `span` or `p` for a
+   * label that is not a heading at all (a legend group's title).
+   */
+  as?: SectionLabelElement;
+  size?: SectionLabelSize;
+  children: ReactNode;
+}
+
+/**
+ * A section's small uppercase label. lenkbank spells
+ * `text-xs font-semibold uppercase tracking-wide text-slate-500 dark:text-slate-400`
+ * on every `<h3>` of its control page and more; keksdose's budget switcher writes the
+ * 10px version on a menu row. One component, the token colour, and the level chosen
+ * where the outline is known.
+ */
+export function SectionLabel({ as = "h3", size = "sm", className, children, ...rest }: SectionLabelProps) {
+  const Tag = as as ElementType;
+  return (
+    <Tag {...rest} className={cn(SECTION_LABEL_CLASS[size], className)}>
+      {children}
+    </Tag>
+  );
+}
+
+/* ── Caption ──────────────────────────────────────────────────────────────── */
+
+/**
+ * The caption type as a class string: 11px, snug, muted. lenkbank's `CAPTION`
+ * (shared/ui/caption.ts:23) — written out 31 times before it was a constant — as a
+ * token colour rather than `slate-500 dark:slate-400`, so it follows the palette.
+ * Exported for the same reason lenkbank's is a string: every caller positions it
+ * differently (`mt-1`, `self-end pb-2`, `border-t`), and what must be one thing is the
+ * type, not the box.
+ */
+export const CAPTION_CLASS = "text-[11px] leading-snug text-[var(--text-muted)]";
+
+export interface CaptionProps extends ComponentPropsWithoutRef<"p"> {
+  /** Default `p`; `span` for a caption inside a line of other content. */
+  as?: "p" | "span" | "div";
+  children: ReactNode;
+}
+
+/**
+ * The small grey sentence under a field, a table or a button — prose ABOUT the thing
+ * above it. Not `FieldHint`, which hides behind a field label's "?" so a paragraph does
+ * not make one field taller than its neighbour (lenkbank feedback #27).
+ */
+export function Caption({ as = "p", className, children, ...rest }: CaptionProps) {
+  const Tag = as as ElementType;
+  return (
+    <Tag {...rest} className={cn(CAPTION_CLASS, className)}>
+      {children}
+    </Tag>
+  );
+}