@eifi1/ui-kit 0.10.0 → 0.11.0

package/src/components/progress-bar.tsx

@@ -41,6 +41,49 @@ const FILL: Record<ProgressBarTone, string> = {
 
 const TRACK_HEIGHT: Record<ProgressBarSize, string> = { sm: "h-1", slim: "h-1.5", md: "h-2", lg: "h-3" };
 
+// A segment with no tone of its own takes the next categorical chart colour, so a
+// stacked bar of unnamed parts is still a set of tellable parts rather than one fill.
+const SERIES_FILL = [
+  "bg-[var(--chart-1)]",
+  "bg-[var(--chart-2)]",
+  "bg-[var(--chart-3)]",
+  "bg-[var(--chart-4)]",
+  "bg-[var(--chart-5)]",
+  "bg-[var(--chart-6)]",
+  "bg-[var(--chart-7)]",
+  "bg-[var(--chart-8)]",
+  "bg-[var(--chart-9)]",
+];
+
+/** Each segment's fill classes: its own classes, else its tone, else (with no `color`)
+ *  the next chart colour. "Next" counts the UNCOLOURED segments only — a segment with
+ *  its own `className`/`tone`/`color` does not use up `--chart-1`, so an "Other" in grey
+ *  ahead of two plain parts leaves them `--chart-1` and `--chart-2`. */
+function segmentFills(segments: ProgressBarSegment[]): Array<string | undefined> {
+  let next = 0;
+  return segments.map((seg) => {
+    if (seg.className) return seg.className;
+    if (seg.tone) return FILL[seg.tone];
+    return seg.color ? undefined : SERIES_FILL[next++ % SERIES_FILL.length];
+  });
+}
+
+/** One part of a stacked bar. See {@link ProgressBarProps.segments}. */
+export interface ProgressBarSegment {
+  /** Its size, on the bar's own `min`–`max` scale. */
+  value: number;
+  /** A kit tone. Left out (and no `color`/`className`), the next `--chart-N` colour. */
+  tone?: ProgressBarTone;
+  /** Any CSS colour (`var(--token)`), for a palette the tones do not cover. Wins over `tone`. */
+  color?: string;
+  /** Classes for the segment's fill — keksdose's `STEP_CLASS` ramp. Wins over `tone`. */
+  className?: string;
+  /** The part's name: said in the bar's `aria-valuetext` and shown in the legend. */
+  label?: ReactNode;
+  /** A stable React key, when `label` is not a string. */
+  key?: string;
+}
+
 export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "role"> {
   /** Where it stands. Leave it undefined for an INDETERMINATE bar — work is under way
    *  and nobody knows how much is left (an import that reports no count). */
@@ -69,6 +112,20 @@ export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">,
   tone?: ProgressBarTone;
   size?: ProgressBarSize;
   locale?: string;
+  /**
+   * Draw a METER OF PARTS: one bar, several fills side by side in order, a 2px gap
+   * between them — keksdose's discretionary-spending bar (cut-card:133), a whole
+   * split into the steps of a scale. Forces `variant="meter"`: parts of a whole are
+   * never "busy". `aria-valuenow` is the sum; `aria-valuetext` names every part
+   * ("Rent: 40%, Food: 25%"), each part's value through `formatValue` and joined in the
+   * kit's locale — the words keksdose's hand-drawn bar had to hide from a reader
+   * altogether, leaving the legend as the only way in. The sum is clamped to `max`,
+   * and parts past it are cut off at the track's end.
+   */
+  segments?: ProgressBarSegment[];
+  /** With `segments`: a list under the bar naming each part with its swatch and value
+   *  — the table view of the bar, in text tokens rather than the segment colour. */
+  legend?: boolean;
 }
 
 /**
@@ -99,6 +156,8 @@ export function ProgressBar({
   tone = "brand",
   size = "md",
   locale,
+  segments,
+  legend = false,
   className,
   "aria-label": ariaLabel,
   "aria-labelledby": ariaLabelledBy,
@@ -108,19 +167,37 @@ export function ProgressBar({
   const kitLocale = useKitLocale(locale);
   const labelId = useId();
 
-  const meter = variant === "meter";
-  const current = value === undefined || !Number.isFinite(value) ? (meter ? min : undefined) : value;
-  const indeterminate = current === undefined;
+  const stacked = segments !== undefined;
+  const meter = stacked || variant === "meter";
   const span = max - min;
+  const partValue = (v: number) => (Number.isFinite(v) ? Math.max(0, v - min) : 0);
+  const fills = stacked ? segmentFills(segments) : [];
+  const partTotal = stacked ? min + segments.reduce((sum, seg) => sum + partValue(seg.value), 0) : undefined;
+  const format = (v: number) =>
+    formatValue
+      ? formatValue(v, max, min)
+      : new Intl.NumberFormat(kitLocale, { style: "percent", maximumFractionDigits: 0 }).format(
+          span <= 0 ? 0 : (Math.min(max, Math.max(min, v)) - min) / span,
+        );
+  const partTexts = stacked
+    ? segments.map((seg) => {
+        const text = format(min + partValue(seg.value));
+        return typeof seg.label === "string" || typeof seg.label === "number"
+          ? common.fieldValue(String(seg.label), text)
+          : text;
+      })
+    : [];
+  const current =
+    partTotal ?? (value === undefined || !Number.isFinite(value) ? (meter ? min : undefined) : value);
+  const indeterminate = current === undefined;
   const clamped = indeterminate ? undefined : Math.min(max, Math.max(min, current));
   const fraction = clamped === undefined || span <= 0 ? 0 : (clamped - min) / span;
 
-  const valueText =
-    clamped === undefined
-      ? undefined
-      : formatValue
-        ? formatValue(clamped, max, min)
-        : new Intl.NumberFormat(kitLocale, { style: "percent", maximumFractionDigits: 0 }).format(fraction);
+  const valueText = clamped === undefined ? undefined : format(clamped);
+  const ariaValueText =
+    stacked && partTexts.length > 0
+      ? new Intl.ListFormat(kitLocale, { style: "short", type: "unit" }).format(partTexts)
+      : valueText;
 
   const labelledBy = ariaLabelledBy ?? (label != null ? labelId : undefined);
   const name = labelledBy ? undefined : (ariaLabel ?? (indeterminate ? common.loading : undefined));
@@ -151,13 +228,32 @@ export function ProgressBar({
         aria-valuemin={indeterminate ? undefined : min}
         aria-valuemax={indeterminate ? undefined : max}
         aria-valuenow={clamped}
-        aria-valuetext={valueText}
+        aria-valuetext={ariaValueText}
         aria-busy={!meter && indeterminate ? true : undefined}
         // `relative` + `overflow-hidden`: the indeterminate segment is positioned in
         // here and must not paint past the rounded ends.
         className={cn("relative w-full overflow-hidden rounded-full bg-[var(--bg-active)]", TRACK_HEIGHT[size])}
       >
-        {indeterminate ? (
+        {stacked ? (
+          // The parts in a flex row with a 2px gap, so two neighbouring steps of one
+          // hue are parted by the track rather than by their difference in lightness.
+          <div className="flex h-full w-full gap-0.5">
+            {segments.map((seg, i) => (
+              <div
+                key={seg.key ?? i}
+                data-part="segment"
+                className={cn(
+                  "h-full shrink-0 rounded-full transition-[width] duration-300 motion-reduce:transition-none",
+                  fills[i],
+                )}
+                style={{
+                  width: `${span <= 0 ? 0 : (partValue(seg.value) / span) * 100}%`,
+                  backgroundColor: seg.className ? undefined : seg.color,
+                }}
+              />
+            ))}
+          </div>
+        ) : indeterminate ? (
           <div
             data-part="fill"
             className={cn(
@@ -182,6 +278,28 @@ export function ProgressBar({
           />
         )}
       </div>
+      {stacked && legend && segments.length > 0 && (
+        <ul className="mt-2 space-y-1 text-sm" data-part="legend">
+          {segments.map((seg, i) => (
+            <li key={seg.key ?? i} className="flex items-center gap-2">
+              <span
+                aria-hidden
+                className={cn(
+                  "size-2.5 shrink-0 rounded-sm",
+                  fills[i],
+                )}
+                style={{ backgroundColor: seg.className ? undefined : seg.color }}
+              />
+              {seg.label != null && (
+                <span className="min-w-0 flex-1 truncate text-[var(--text-secondary)]">{seg.label}</span>
+              )}
+              <span className="ms-auto shrink-0 text-xs tabular-nums text-[var(--text-muted)]">
+                {format(min + partValue(seg.value))}
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
     </div>
   );
 }

package/src/components/series-chart.tsx

@@ -129,6 +129,18 @@ export interface SeriesChartSeries {
    * `{ r }` sets its radius. Default: recharts' dot. Bars have none, and ignore it.
    */
   activeDot?: boolean | { r?: number };
+  /**
+   * The shortest a bar of this series is drawn, in px — recharts' `minPointSize`. A
+   * zero or a value too small to see keeps a visible stub, so an empty slot still reads
+   * as a slot with a value rather than a gap: keksdose's weekday pattern, where a
+   * Sunday with no spending drew a 2% stub by hand. Only the DRAWING changes: the axis
+   * is fitted to the values, and the tooltip, the keyboard stops and every accessible
+   * name still say 0. A hole (no value in the row) stays a hole. Overrides the chart's
+   * {@link SeriesChartProps.minBarLength}; `0` turns it off for this series. Meant for
+   * unstacked bars — in a `stack` the stub is drawn over the layer above it. Lines and
+   * areas ignore it.
+   */
+  minBarLength?: number;
 }
 
 /** What a series draws. See {@link SeriesChartSeries.type}. */
@@ -507,6 +519,10 @@ export interface SeriesChartProps {
   locale?: string;
   /** Onto the chart's root (`ChartContainer`) — e.g. an app's own grid ink. */
   className?: string;
+  /** The shortest bar drawn, in px, for every bar series that does not set its own
+   *  {@link SeriesChartSeries.minBarLength}. Drawing only: domain, tooltip and names
+   *  keep the real value. Default: none — a zero draws nothing. */
+  minBarLength?: number;
 }
 
 /** How much of an axis band the rotated title takes, in px. Reserved rather than
@@ -1011,6 +1027,7 @@ function SeriesPlot({
   labels: labelsProp,
   locale: localeProp,
   className,
+  minBarLength,
 }: PlotProps) {
   const labels = useKitLabels("seriesChart", DEFAULT_SERIES_CHART_LABELS, labelsProp);
   const locale = useKitLocale(localeProp);
@@ -1418,6 +1435,7 @@ function SeriesPlot({
           const curve = entry.step ? "stepAfter" : (entry.curve ?? "monotone");
           const width = entry.strokeWidth ?? (entry.step ? STEP_WIDTH : LINE_WIDTH);
           if (type === "bar") {
+            const stub = entry.minBarLength ?? minBarLength;
             return (
               <Bar
                 key={entry.key}
@@ -1427,6 +1445,9 @@ function SeriesPlot({
                 fill={color}
                 fillOpacity={entry.fillOpacity}
                 radius={entry.stack === undefined ? BAR_RADIUS : 0}
+                // Read off the row rather than recharts' `value`: in a stack that is the
+                // layer's running top, which a hole has too — and a hole gets no stub.
+                {...(stub ? { minPointSize: (_value: unknown, index: number) => (finite(plotted[index]?.[entry.key]) === undefined ? 0 : stub) } : {})}
                 // 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) } : {})}

package/src/components/status-dot.tsx

@@ -1,14 +1,17 @@
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import type { ProgressBarTone } from "./progress-bar";
+import type { ChipHue } from "./chip";
 
 /**
  * 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".
+ * swatch for income is money, not "success". Chip's categorical hues are here too
+ * (0.11): a unit-status dot in a combobox (kastlan lease-unit-step.tsx:35, "rented"
+ * is blue) must match the Chip that states the same status elsewhere.
  */
-export type StatusDotTone = ProgressBarTone;
+export type StatusDotTone = ProgressBarTone | ChipHue;
 
 /** `sm` 8px (keksdose's unread dot on the support trigger), `md` 10px (the avatar's
  *  unread dot), `lg` 12px (kastlan's occupancy legend swatch). */
@@ -23,6 +26,11 @@ const FILL: Record<StatusDotTone, string> = {
   info: "bg-[var(--info)]",
   income: "bg-[var(--money-income)]",
   expense: "bg-[var(--money-expense)]",
+  blue: "bg-[var(--hue-blue)]",
+  indigo: "bg-[var(--hue-indigo)]",
+  purple: "bg-[var(--hue-purple)]",
+  teal: "bg-[var(--hue-teal)]",
+  orange: "bg-[var(--hue-orange)]",
 };
 
 const SIZE: Record<StatusDotSize, string> = { sm: "size-2", md: "size-2.5", lg: "size-3" };

package/src/components/table.tsx

@@ -13,6 +13,21 @@ export type TableDensity = "comfortable" | "compact" | "none";
  *  figures for room. */
 export type TableLayout = "auto" | "fixed";
 export type TableAlign = "start" | "center" | "end";
+/**
+ * Vertical alignment of a cell's content (0.11.0). The defaults stay as they were — a
+ * head cell sits on the `bottom` (a wrapped heading ends on the line above the
+ * figures), a body cell at the `top` (a wrapped note starts level with its row). A
+ * table whose cells are INPUTS wants `middle`: keksdose's VAT summary
+ * (invoices/vat-summary.tsx) sets fields beside derived read-out figures in one row,
+ * and a figure at the top of its cell sat above the middle of the field next to it —
+ * so it writes `<tr className="align-middle">` over raw `<th>`/`<td>`, because the
+ * kit's cells each stated `align-top` and a class on the row could not reach them.
+ */
+export type TableVAlign = "top" | "middle" | "bottom";
+/** The head cell's type size: `xs` (the head's default) or `sm` (the body's). */
+export type TableHeaderCellSize = "xs" | "sm";
+/** The header cell's weight. Default `medium`. */
+export type TableHeaderCellWeight = "normal" | "medium" | "semibold";
 
 interface TableContextValue {
   density: TableDensity;
@@ -33,6 +48,28 @@ const TableContext = createContext<TableContextValue>({
 /** Which section a row sits in — zebra and hover apply to body rows only. */
 const SectionContext = createContext<"head" | "body" | "foot">("body");
 
+/** A {@link TableRow}'s `valign`, which its cells take unless they set their own. It
+ *  cannot be left to CSS inheritance: every cell states its own default alignment,
+ *  and a class on the cell beats one on the row. */
+const RowVAlignContext = createContext<TableVAlign | undefined>(undefined);
+
+const VALIGN: Record<TableVAlign, string> = {
+  top: "align-top",
+  middle: "align-middle",
+  bottom: "align-bottom",
+};
+
+const HEADER_SIZE: Record<TableHeaderCellSize, string> = {
+  xs: "text-xs",
+  sm: "text-sm",
+};
+
+const HEADER_WEIGHT: Record<TableHeaderCellWeight, string> = {
+  normal: "font-normal",
+  medium: "font-medium",
+  semibold: "font-semibold",
+};
+
 const CELL_PAD: Record<TableDensity, string> = {
   comfortable: "px-3 py-2",
   compact: "px-2 py-1",
@@ -125,6 +162,7 @@ export function Table({
         {...(overflowing ? regionName : null)}
         tabIndex={overflowing ? 0 : undefined}
         data-overflowing={overflowing || undefined}
+        data-clips=""
         className={cn(
           // `relative`: the containing block for an `sr-only` caption.
           "relative w-full overflow-x-auto",
@@ -252,23 +290,31 @@ export function TableFoot({ className, ...rest }: TableFootProps) {
   );
 }
 
-export type TableRowProps = ComponentPropsWithoutRef<"tr">;
+/** The deprecated HTML `valign` attribute is replaced by a class-backed one. */
+export interface TableRowProps extends ComponentPropsWithoutRef<"tr"> {
+  /** Vertical alignment for every cell of the row that does not set its own. See
+   *  {@link TableVAlign}. Left out, each cell keeps its default. */
+  valign?: TableVAlign;
+}
 
-export function TableRow({ className, ...rest }: TableRowProps) {
+export function TableRow({ valign, className, ...rest }: TableRowProps) {
   const { zebra, hover } = useContext(TableContext);
   const section = useContext(SectionContext);
   const body = section === "body";
-  return (
+  const row = (
     <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)]",
+        // On the row as well, for a raw `<td>` of the caller's, which inherits it.
+        valign && VALIGN[valign],
         className,
       )}
     />
   );
+  return valign ? <RowVAlignContext.Provider value={valign}>{row}</RowVAlignContext.Provider> : row;
 }
 
 interface CellAlignProps {
@@ -276,19 +322,44 @@ interface CellAlignProps {
   numeric?: boolean;
   /** Logical alignment. Default `start` (`end` when `numeric`). */
   align?: TableAlign;
+  /** Vertical alignment. Default: the row's `valign`, else `bottom` for a head cell and
+   *  `top` for a body cell. See {@link TableVAlign}. */
+  valign?: TableVAlign;
 }
 
-/** The deprecated HTML `align` attribute is replaced by a logical one. */
-export interface TableHeaderCellProps extends Omit<ComponentPropsWithoutRef<"th">, "align">, CellAlignProps {}
+/** The deprecated HTML `align` and `valign` attributes are replaced by class-backed ones. */
+export interface TableHeaderCellProps extends Omit<ComponentPropsWithoutRef<"th">, "align" | "valign">, CellAlignProps {
+  /**
+   * Type size. Left out: `xs` in the head, the table's own size in the body — as
+   * before. keksdose's VAT summary heads its columns at the body size and normal weight
+   * (vat-summary.tsx:158–168, `font-normal` on each `<th>`), a quiet header over a
+   * small table of figures, and could not say so without overriding classes.
+   */
+  size?: TableHeaderCellSize;
+  /** Default `medium`. `normal` for the quiet header above; see {@link size}. */
+  weight?: TableHeaderCellWeight;
+}
 
 /**
  * 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) {
+export function TableHeaderCell({
+  numeric = false,
+  align,
+  valign,
+  size,
+  weight = "medium",
+  scope,
+  className,
+  ...rest
+}: TableHeaderCellProps) {
   const { density } = useContext(TableContext);
   const section = useContext(SectionContext);
+  const rowVAlign = useContext(RowVAlignContext);
+  const head = section === "head";
+  const textSize = size ?? (head ? "xs" : undefined);
   return (
     <th
       {...rest}
@@ -297,24 +368,27 @@ export function TableHeaderCell({ numeric = false, align, scope, className, ...r
         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)]",
+        VALIGN[valign ?? rowVAlign ?? (head ? "bottom" : "top")],
+        HEADER_WEIGHT[weight],
+        head ? "text-[var(--text-muted)]" : "text-[var(--text-secondary)]",
+        textSize && HEADER_SIZE[textSize],
         className,
       )}
     />
   );
 }
 
-export interface TableCellProps extends Omit<ComponentPropsWithoutRef<"td">, "align">, CellAlignProps {}
+export interface TableCellProps extends Omit<ComponentPropsWithoutRef<"td">, "align" | "valign">, CellAlignProps {}
 
-export function TableCell({ numeric = false, align, className, ...rest }: TableCellProps) {
+export function TableCell({ numeric = false, align, valign, className, ...rest }: TableCellProps) {
   const { density } = useContext(TableContext);
+  const rowVAlign = useContext(RowVAlignContext);
   return (
     <td
       {...rest}
       className={cn(
         CELL_PAD[density],
-        "align-top",
+        VALIGN[valign ?? rowVAlign ?? "top"],
         ALIGN[align ?? (numeric ? "end" : "start")],
         numeric && "tabular-nums whitespace-nowrap",
         className,

package/src/components/text.tsx

@@ -9,8 +9,15 @@ import { cn } from "../lib/cn";
  * (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.
+ *
+ * `md` (0.11.0) is 11px, the rung between them: keksdose's budget-summary card labels
+ * its figures ("Assigned", "Activity", "Upcoming", "Available" —
+ * budget-summary-card:258/264/286/297) and its support thread its day divider and a message's meta line
+ * (support-thread:153/223) at `text-[11px]` by hand — 10px read as a footnote under a
+ * figure that size, 12px competed with it. Named `md` rather than slotted in order
+ * because `sm` was already the default and renaming it would move every caller.
  */
-export type SectionLabelSize = "xs" | "sm";
+export type SectionLabelSize = "xs" | "md" | "sm";
 
 /**
  * The small, uppercase, tracked, muted label — as a class string, per size.
@@ -23,6 +30,7 @@ export type SectionLabelSize = "xs" | "sm";
  */
 export const SECTION_LABEL_CLASS: Record<SectionLabelSize, string> = {
   xs: "text-[10px] font-semibold uppercase tracking-wide text-[var(--text-muted)]",
+  md: "text-[11px] font-semibold uppercase tracking-wide text-[var(--text-muted)]",
   sm: "text-xs font-semibold uppercase tracking-wide text-[var(--text-muted)]",
 };
 

package/src/components/toggle-group.tsx

@@ -76,11 +76,25 @@ export interface ToggleGroupBaseProps<T extends string>
   error?: ReactNode;
 }
 
+/**
+ * A line under the group saying what the CHOSEN option means — lenkbank's ToggleField
+ * `hint` (features/gear/common.tsx:97): not help behind a "?" but a caption, and one
+ * that changes as the choice does. Pass a function of the value for that; it is
+ * attached with `aria-describedby`, and a function caption is also a polite live
+ * region, because a description is read when the group is entered and not again when
+ * an arrow key changes the choice underneath it.
+ *
+ * In muted 11px text under the field (or the bare group), above an `error`.
+ */
+type ToggleGroupCaption<V> = ReactNode | ((value: V) => ReactNode);
+
 /** The group as it has always been: one option is always the answer. */
 export interface ToggleGroupRequiredProps<T extends string> extends ToggleGroupBaseProps<T> {
   allowEmpty?: false;
   value: T;
   onChange: (value: T) => void;
+  /** See {@link ToggleGroupCaption}. */
+  caption?: ToggleGroupCaption<T>;
 }
 
 /**
@@ -97,6 +111,8 @@ export interface ToggleGroupClearableProps<T extends string> extends ToggleGroup
   allowEmpty: true;
   value: T | null;
   onChange: (value: T | null) => void;
+  /** See {@link ToggleGroupCaption}. `null` while nothing is chosen. */
+  caption?: ToggleGroupCaption<T | null>;
 }
 
 /** `allowEmpty` picks the shape, so `onChange` is typed `(T) => void` unless the group
@@ -138,7 +154,11 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
   const hasError = field && error !== undefined && error !== null && error !== false && error !== "";
   // Taken off the rest so neither reaches the DOM; `props` keeps them paired, which is
   // what lets the `onChange` below be called with `null` only in the mode that allows it.
-  const { allowEmpty: _allowEmpty, onChange: _onChange, ...rest } = restWithMode;
+  const { allowEmpty: _allowEmpty, onChange: _onChange, caption, ...rest } = restWithMode;
+  const captionId = useId();
+  const captionIsLive = typeof caption === "function";
+  const captionNode = captionIsLive ? (caption as (v: T | null) => ReactNode)(value) : caption;
+  const hasCaption = captionNode !== undefined && captionNode !== null && captionNode !== false && captionNode !== "";
   const choose = (next: T) => {
     if (props.allowEmpty) props.onChange(next === value ? null : next);
     else props.onChange(next);
@@ -185,7 +205,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
       aria-labelledby={field && ariaLabelAttr === undefined && ariaLabel === undefined ? labelId : rest["aria-labelledby"]}
       aria-invalid={hasError || rest["aria-invalid"] || undefined}
       aria-describedby={
-        hasError ? (rest["aria-describedby"] ? `${rest["aria-describedby"]} ${errorId}` : errorId) : rest["aria-describedby"]
+        [rest["aria-describedby"], hasCaption && captionId, hasError && errorId].filter(Boolean).join(" ") || undefined
       }
       // `aria-disabled` on the group as well as `disabled` on each button: a radio
       // group is what the user is being refused, and a screen reader announcing
@@ -273,7 +293,31 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
       })}
     </div>
   );
-  if (!field) return group;
+  // Rendered whenever the caption is — `aria-live` must be on the element BEFORE its
+  // text changes, or the change is not announced — but empty (no height, no margin)
+  // when there is nothing to say, so a function caption that returns null for some
+  // options leaves no gap. Empty rather than `hidden`: some readers do not announce
+  // text that appears inside an element coming back from `display: none`.
+  const captionEl =
+    hasCaption || captionIsLive ? (
+      <p
+        id={captionId}
+        aria-live={captionIsLive ? "polite" : undefined}
+        className={cn("text-[11px] leading-snug text-[var(--text-muted)]", hasCaption && "mt-1")}
+      >
+        {hasCaption ? captionNode : null}
+      </p>
+    ) : null;
+  if (!field) {
+    if (!captionEl) return group;
+    // The group keeps its `className`, as without a caption; the wrapper only stacks.
+    return (
+      <div className="min-w-0">
+        {group}
+        {captionEl}
+      </div>
+    );
+  }
   return (
     // `h-full` + `flex-1`: the chrome fills a grid or stretched flex row, which is what
     // levels it with a select beside it whatever the browser makes of the select.
@@ -294,6 +338,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
           {group}
         </div>
       </FloatingField>
+      {captionEl}
       {hasError && (
         <p id={errorId} className="mt-1 text-[11px] leading-tight text-[var(--danger)]">
           {error}

package/src/components/tooltip.tsx

@@ -17,6 +17,13 @@ import { useAnchoredRect, type AnchorRect } from "../hooks/use-anchored-rect";
 import { dirOf, type Direction } from "../lib/direction";
 import { hasClippingAncestor } from "../lib/clipping";
 
+/** The attribute that marks an element as a clipping container for {@link Tooltip}'s
+ *  auto-portal, whatever its computed `overflow` — `<div data-clips>` or
+ *  `<div {...{ [CLIPS_ATTRIBUTE]: "" }}>`. Put it on an app's own scroller so a test
+ *  environment without stylesheets (jsdom) portals the same tooltips the browser
+ *  does. DataTable's body and Table's wrapper already carry it. */
+export { CLIPS_ATTRIBUTE } from "../lib/clipping";
+
 /** Where the bubble sits. `start` / `end` follow the reading direction — `end` is the
  *  right in LTR and the left in RTL — and are what a layout that mirrors should ask
  *  for. `left` / `right` stay physical, for a bubble tied to something that does not
@@ -75,8 +82,8 @@ export interface TooltipProps extends ComponentPropsWithoutRef<"span"> {
   /**
    * Where the bubble lives. Left out (the default since 0.10.0), the tooltip decides for
    * itself: the bubble stays next to the trigger unless an ancestor clips or scrolls
-   * (`overflow` other than `visible`), in which case it is portalled — see "Inside a
-   * scroll container" below. `true` always portals, `false` never does; both are exactly
+   * (`overflow` other than `visible`, or the {@link CLIPS_ATTRIBUTE} marker), in which
+   * case it is portalled — see "Inside a scroll container" below. `true` always portals, `false` never does; both are exactly
    * what they were before the default existed.
    */
   portal?: boolean;
@@ -144,7 +151,14 @@ type TooltipVariantProps = Omit<TooltipProps, "side" | "portal"> & { side: Toolt
  * being one: every tooltip in a table, a drawer or a scrolling card had to remember it,
  * and the ones that forgot were only found by someone scrolling sideways. So with
  * `portal` left out, the tooltip looks for a clipping ancestor itself — any element
- * between it and `<body>` whose computed `overflow-x` / `overflow-y` is not `visible`.
+ * between it and `<body>` whose computed `overflow-x` / `overflow-y` is not `visible`,
+ * or that carries {@link CLIPS_ATTRIBUTE} (`data-clips`). The marker is what makes the
+ * answer the same under test: jsdom computes no Tailwind, so there every scroller
+ * reads `visible` and a table-cell tooltip used to stay in place — its always-mounted
+ * bubble then repeated the label in the cell's accessible name and `textContent`
+ * ("CheckingChecking"), and apps pinned `portal` to stop it. The kit's own scrollers
+ * are marked, so a tooltip in a DataTable or Table cell portals in jsdom exactly as it
+ * does in the browser.
  * It looks at MOUNT, not only on open: dev#488's phantom scroll is caused by a bubble
  * nobody opened, so a check that waited for the hover would find the damage already
  * done. It looks again on every open, for a container that started scrolling after