@eifi1/ui-kit 0.15.5 → 0.16.0

package/src/components/stat-tile.tsx

@@ -1,4 +1,4 @@
-import { isValidElement, useId, useLayoutEffect, useState } from "react";
+import { createContext, isValidElement, useContext, 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";
@@ -217,6 +217,16 @@ export interface StatTileProps
   loading?: boolean;
   /** `"sm"` for dense grids (a metrics wall); `"md"` the default KPI. */
   size?: "sm" | "md";
+  /**
+   * The tile's frame. `"card"` (default) is the bordered, shadowed card on the page.
+   * `"inset"` is a tile INSIDE a card: {@link Card}'s `inset` — the raised
+   * `--bg-surface-2`, a small radius, no border or shadow, since the card round it
+   * already has them. `"plain"` drops the frame altogether — no fill and no padding —
+   * for figures set straight into a card's content (a summary row under a card title),
+   * where any box would be a box in a box. keksdose wrote both by hand over the card
+   * tile (`border-0 shadow-none bg-transparent p-0`) for its tiles inside a card.
+   */
+  variant?: "card" | "inset" | "plain";
   /** Makes the tile a link. See {@link renderLink} for a router. */
   href?: string;
   /** Renders the link for `href` — pass your router's `<Link>` here, since a plain
@@ -291,6 +301,7 @@ export function StatTile({
   sensitive = false,
   loading = false,
   size = "md",
+  variant = "card",
   href,
   renderLink,
   onClick,
@@ -299,6 +310,11 @@ export function StatTile({
   ...rest
 }: StatTileProps) {
   const text = useKitLabels("statTile", DEFAULT_STAT_TILE_LABELS, labels);
+  // A loading StatTileGrid puts every tile in it into the loading state and says
+  // "Loading…" ONCE for all of them; the tile then keeps its own sentence to itself
+  // (see StatTileGrid's `loading`).
+  const gridLoading = useContext(StatTileGridLoadingContext);
+  loading = loading || gridLoading;
   const kitLink = useKitLink();
   const [labelEl, setLabelEl] = useState<HTMLElement | null>(null);
   const labelCut = useIsTruncated(truncateLabel ? labelEl : null);
@@ -398,7 +414,7 @@ export function StatTile({
   const headline = loading ? (
     <span id={valueId} className="relative block py-0.5">
       <span aria-hidden className={cn(SKELETON_CLASS, "block h-6 w-24 max-w-full")} />
-      <span className="sr-only">{text.loading}</span>
+      {!gridLoading && <span className="sr-only">{text.loading}</span>}
     </span>
   ) : hasValue ? (
     <span id={valueId} data-private={priv} className={cn(valueClass, valueLabel != null && "ms-auto")}>
@@ -432,13 +448,18 @@ export function StatTile({
   return (
     <Card
       {...rest}
+      variant={variant === "card" ? "default" : "inset"}
+      data-variant={variant === "card" ? undefined : variant}
       aria-busy={loading || undefined}
       className={cn(
         // @container: the headline sizes read the tile's width. relative: the stretched
         // link's overlay. overflow-hidden: at pathological widths a figure clips inside
         // the border instead of painting over the neighbouring tile.
         "@container relative flex min-w-0 flex-col overflow-hidden",
-        PADDING[size],
+        // `plain` is the inset card with its fill and padding taken away — the figures
+        // align with the content edge of the card they sit in. (Not `p-0` over the
+        // padding: the padding's `sm:p-4` would still win from `sm` up.)
+        variant === "plain" ? "rounded-none bg-transparent p-0" : PADDING[size],
         interactive && "transition-colors hover:border-[var(--border-strong)] hover:bg-[var(--bg-hover)]",
         className,
       )}
@@ -577,8 +598,30 @@ 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. */
   minTileWidth?: string;
+  /**
+   * Let a row that is not full stretch its tiles across the whole width. Default
+   * `true` (CSS `auto-fit`): one or two tiles fill the row, as they always have.
+   * `false` (`auto-fill`): the empty columns are kept, so every tile is the width of
+   * a column whatever the count — a lone "Balance" tile in a card stays tile-sized
+   * instead of becoming a banner the width of the card, and the tiles of a short row
+   * line up with the columns of a full one above it.
+   */
+  stretch?: boolean;
+  /**
+   * Every tile in the grid is loading: each shows its skeleton (as with its own
+   * `loading`), and the grid says "Loading…" ONCE, in a polite status region, instead
+   * of each tile carrying its own sr-only "Loading…" — a wall of eight tiles was read
+   * as eight "Loading…"s in a row. The grid is `aria-busy` meanwhile. A tile's own
+   * `loading` inside a grid that is not loading still speaks for itself.
+   */
+  loading?: boolean;
+  /** The grid's one sentence — `loading` from {@link StatTileLabels}. */
+  labels?: Partial<Pick<StatTileLabels, "loading">>;
 }
 
+/** Set by a loading {@link StatTileGrid}; read by each tile in it. */
+const StatTileGridLoadingContext = createContext(false);
+
 /**
  * The row of tiles every dashboard in the three apps lays out by hand, each with its
  * own breakpoint ladder (`grid-cols-2 md:grid-cols-4 min-[2400px]:grid-cols-8` …).
@@ -586,9 +629,36 @@ export interface StatTileGridProps extends ComponentPropsWithoutRef<"div"> {
  * the band where the sidebar was open. This fits as many columns as `minTileWidth`
  * allows in the space the grid actually has, and needs no breakpoint at all.
  */
-export function StatTileGrid({ minTileWidth = "9rem", className, style, ...rest }: StatTileGridProps) {
+export function StatTileGrid({
+  minTileWidth = "9rem",
+  stretch = true,
+  loading = false,
+  labels,
+  className,
+  style,
+  children,
+  ...rest
+}: StatTileGridProps) {
+  const text = useKitLabels("statTile", DEFAULT_STAT_TILE_LABELS, labels);
   const columns: CSSProperties = {
-    gridTemplateColumns: `repeat(auto-fit, minmax(min(100%, ${minTileWidth}), 1fr))`,
+    gridTemplateColumns: `repeat(${stretch ? "auto-fit" : "auto-fill"}, minmax(min(100%, ${minTileWidth}), 1fr))`,
   };
-  return <div {...rest} className={cn("grid gap-3", className)} style={{ ...columns, ...style }} />;
+  return (
+    <div
+      {...rest}
+      aria-busy={loading || rest["aria-busy"] || undefined}
+      // `relative`: the containing block for the sr-only status, which is absolutely
+      // positioned and so also takes no grid cell.
+      className={cn("relative grid gap-3", className)}
+      style={{ ...columns, ...style }}
+    >
+      {/* Always mounted, filled while loading: a live region announces a CHANGE of
+          its content, so one that appeared already holding the sentence might say
+          nothing. */}
+      <span role="status" className="sr-only">
+        {loading ? text.loading : ""}
+      </span>
+      <StatTileGridLoadingContext.Provider value={loading}>{children}</StatTileGridLoadingContext.Provider>
+    </div>
+  );
 }

package/src/components/status-dot.tsx

@@ -33,6 +33,37 @@ const FILL: Record<StatusDotTone, string> = {
   orange: "bg-[var(--hue-orange)]",
 };
 
+/**
+ * The colour of each tone as a CSS value — the same `var(--…)` the dot's class paints
+ * with. For a mark the kit does not draw: a `SwatchPicker` option (`color`), a chart
+ * series, an inline `style`. keksdose's category picker spelled `var(--hue-teal)` out by
+ * hand to match the dot beside the category name; a renamed token would have parted
+ * them silently. (The class table above stays literal: Tailwind finds classes by
+ * reading the source, so `bg-[${…}]` would never be generated. A test keeps the two
+ * tables agreeing.)
+ */
+const COLOR: Record<StatusDotTone, string> = {
+  brand: "var(--brand)",
+  neutral: "var(--text-muted)",
+  success: "var(--success)",
+  warning: "var(--warning)",
+  danger: "var(--danger)",
+  info: "var(--info)",
+  income: "var(--money-income)",
+  expense: "var(--money-expense)",
+  blue: "var(--hue-blue)",
+  indigo: "var(--hue-indigo)",
+  purple: "var(--hue-purple)",
+  teal: "var(--hue-teal)",
+  orange: "var(--hue-orange)",
+};
+
+/** The CSS colour a {@link StatusDot} of `tone` is filled with — `statusDotColor("teal")`
+ *  is `"var(--hue-teal)"`. See the table above for when to reach for it. */
+export function statusDotColor(tone: StatusDotTone): string {
+  return COLOR[tone];
+}
+
 const SIZE: Record<StatusDotSize, string> = { sm: "size-2", md: "size-2.5", lg: "size-3" };
 
 export interface StatusDotProps extends Omit<ComponentPropsWithoutRef<"span">, "children"> {

package/src/components/swatch-picker.tsx

@@ -21,7 +21,9 @@ export interface SwatchOption<T extends string> {
   value: T;
   /** Any CSS colour — a token (`var(--chart-3)`), a hex, an `oklch()`. Painted as an
    *  inline background, so it does not have to be a class the kit's CSS knows.
-   *  Leave it out when `swatchClassName` paints the dot instead. */
+   *  Leave it out when `swatchClassName` paints the dot instead. For a colour that
+   *  must match a `StatusDot` / `Chip` hue elsewhere, `statusDotColor("teal")` rather
+   *  than `"var(--hue-teal)"` written out — one table, so the two cannot drift. */
   color?: string;
   /** The colour's name, in the user's language. Shown in the bubble and read out;
    *  required, because a swatch with no name is a colour only some people can read. */

package/src/components/table.tsx

@@ -1,6 +1,7 @@
-import { Children, createContext, useContext, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { Children, createContext, useCallback, useContext, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+import type { ComponentPropsWithRef, ReactNode, Ref } from "react";
 import { cn } from "../lib/cn";
+import { assignRef } from "./choice-parts";
 import { THIN_SCROLLBAR_CLASS, useScrollOverflow } from "./scroll-area";
 
 /** `none` (0.10.0): no cell padding at all — keksdose's VAT summary, a table set
@@ -91,6 +92,22 @@ function useSection<E extends HTMLElement>(): [TableSection, ((el: E | null) =>
   return [fromContext ?? detected ?? "body", fromContext === undefined ? setNode : undefined];
 }
 
+/**
+ * One callback ref for the caller's `ref` and the part's own (0.16.0). Every part takes
+ * a `ref` to its DOM element — React 19 hands it to a function component as a prop —
+ * and the parts that hold the node themselves (the table, a row or a head cell reading
+ * its section off the DOM) must still get it when the caller passes one too.
+ */
+function useMergedRef<E>(own: ((el: E | null) => void) | { current: E | null } | undefined, ref: Ref<E> | undefined) {
+  return useCallback(
+    (node: E | null) => {
+      assignRef(own as Ref<E> | undefined, node);
+      assignRef(ref, node);
+    },
+    [own, ref],
+  );
+}
+
 /** 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. */
@@ -133,7 +150,12 @@ const ALIGN: Record<TableAlign, string> = {
  */
 export const NUMERIC_CELL_CLASS = "text-end tabular-nums";
 
-export interface TableProps extends ComponentPropsWithoutRef<"table"> {
+/**
+ * Every part's props are `ComponentPropsWithRef` (0.16.0), so `ref` reaches the DOM
+ * element: keksdose scrolled a budget row into view through `useId` + `getElementById`
+ * because `<TableRow ref>` did not type-check.
+ */
+export interface TableProps extends ComponentPropsWithRef<"table"> {
   /** `compact` for a dense detail view (a ledger, a spec sheet). */
   density?: TableDensity;
   /** Tint every other body row. */
@@ -216,6 +238,7 @@ export function Table({
   stack,
   className,
   "aria-label": ariaLabel,
+  ref,
   ...rest
 }: TableProps) {
   const captionId = useId();
@@ -223,6 +246,7 @@ export function Table({
   const wrapper = useRef<HTMLDivElement | null>(null);
   const overflowing = useScrollOverflow(wrapper);
   const tableRef = useRef<HTMLTableElement | null>(null);
+  const setTableRef = useMergedRef(tableRef, ref);
 
   // `stack="phone"`: label every body cell with its column's header text, and keep the
   // table's roles explicit — `display: block` on table parts drops their table
@@ -296,7 +320,7 @@ export function Table({
       >
         <table
           {...rest}
-          ref={tableRef}
+          ref={setTableRef}
           aria-label={ariaLabel}
           className={cn(
             "w-full caption-bottom border-collapse text-sm text-[var(--text-primary)]",
@@ -312,7 +336,7 @@ export function Table({
   );
 }
 
-export interface TableHeadProps extends ComponentPropsWithoutRef<"thead"> {
+export interface TableHeadProps extends ComponentPropsWithRef<"thead"> {
   /** The rule under the head. Default true; `false` for a quiet header over a small
    *  table (keksdose's VAT summary wrote `className="border-b-0"` to lose it). */
   bordered?: boolean;
@@ -326,7 +350,7 @@ export function TableHead({ bordered = true, className, ...rest }: TableHeadProp
   );
 }
 
-export interface TableBodyProps extends ComponentPropsWithoutRef<"tbody"> {
+export interface TableBodyProps extends ComponentPropsWithRef<"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-
@@ -354,7 +378,7 @@ export function TableBody({ className, empty, children, ...rest }: TableBodyProp
   );
 }
 
-export interface TableEmptyProps extends Omit<ComponentPropsWithoutRef<"tr">, "children"> {
+export interface TableEmptyProps extends Omit<ComponentPropsWithRef<"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. */
@@ -407,7 +431,7 @@ export function TableEmpty({ children, colSpan, cellClassName, className, ...res
   );
 }
 
-export type TableFootProps = ComponentPropsWithoutRef<"tfoot">;
+export type TableFootProps = ComponentPropsWithRef<"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. */
@@ -429,7 +453,7 @@ const ROW_VARIANT: Record<TableRowVariant, string | false> = {
 };
 
 /** The deprecated HTML `valign` attribute is replaced by a class-backed one. */
-export interface TableRowProps extends ComponentPropsWithoutRef<"tr"> {
+export interface TableRowProps extends ComponentPropsWithRef<"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;
@@ -440,9 +464,10 @@ export interface TableRowProps extends ComponentPropsWithoutRef<"tr"> {
   bordered?: boolean;
 }
 
-export function TableRow({ valign, variant = "row", bordered, className, ...rest }: TableRowProps) {
+export function TableRow({ valign, variant = "row", bordered, className, ref: refProp, ...rest }: TableRowProps) {
   const { zebra, hover, rowDividers } = useContext(TableContext);
-  const [section, ref] = useSection<HTMLTableRowElement>();
+  const [section, sectionRef] = useSection<HTMLTableRowElement>();
+  const ref = useMergedRef(sectionRef, refProp);
   const body = section === "body";
   const record = body && variant === "row";
   const row = (
@@ -475,7 +500,7 @@ interface CellAlignProps {
 }
 
 /** The deprecated HTML `align` and `valign` attributes are replaced by class-backed ones. */
-export interface TableHeaderCellProps extends Omit<ComponentPropsWithoutRef<"th">, "align" | "valign">, CellAlignProps {
+export interface TableHeaderCellProps extends Omit<ComponentPropsWithRef<"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
@@ -500,10 +525,12 @@ export function TableHeaderCell({
   weight = "medium",
   scope,
   className,
+  ref: refProp,
   ...rest
 }: TableHeaderCellProps) {
   const { density } = useContext(TableContext);
-  const [section, ref] = useSection<HTMLTableCellElement>();
+  const [section, sectionRef] = useSection<HTMLTableCellElement>();
+  const ref = useMergedRef(sectionRef, refProp);
   const rowVAlign = useContext(RowVAlignContext);
   const head = section === "head";
   const textSize = size ?? (head ? "xs" : undefined);
@@ -526,7 +553,7 @@ export function TableHeaderCell({
   );
 }
 
-export interface TableCellProps extends Omit<ComponentPropsWithoutRef<"td">, "align" | "valign">, CellAlignProps {}
+export interface TableCellProps extends Omit<ComponentPropsWithRef<"td">, "align" | "valign">, CellAlignProps {}
 
 export function TableCell({ numeric = false, align, valign, className, ...rest }: TableCellProps) {
   const { density } = useContext(TableContext);
@@ -545,7 +572,7 @@ export function TableCell({ numeric = false, align, valign, className, ...rest }
   );
 }
 
-export type TableCaptionProps = ComponentPropsWithoutRef<"caption">;
+export type TableCaptionProps = ComponentPropsWithRef<"caption">;
 
 /**
  * The table's title. Beneath the table by default (`caption-bottom`, the shadcn

package/src/components/toggle-legend.tsx

@@ -194,6 +194,17 @@ export interface StaticLegendProps {
   orientation?: "horizontal" | "vertical";
   /** The list's accessible name. Default: the `seriesChart.legend` label. */
   "aria-label"?: string;
+  /**
+   * `ul` (default): a list — "list, 4 items", walked with the list keys. Its entries are
+   * `listitem`s, so a host test that counts `getAllByRole("listitem")` on a page with
+   * the legend on it counts the legend too: scope it (`within(...)`) or use `div`.
+   *
+   * `div`: a named `role="group"` of plain entries, for a legend set inside something
+   * that is already a list or a table row, where a list in a list reads as nesting that
+   * is not there, or where the entries are too few for "list, 2 items" to help. The
+   * entries are read in order either way; only the list framing goes.
+   */
+  as?: "ul" | "div";
   className?: string;
   /** Per-instance strings over `<UiKitProvider labels={{ seriesChart }}>`. */
   labels?: Partial<SeriesChartLabels>;
@@ -218,13 +229,19 @@ export function StaticLegend({
   entries,
   orientation = "horizontal",
   "aria-label": ariaLabel,
+  as = "ul",
   className,
   labels: labelsProp,
 }: StaticLegendProps) {
   const labels = useKitLabels("seriesChart", DEFAULT_SERIES_CHART_LABELS, labelsProp);
   if (entries.length === 0) return null;
+  const List = as;
+  const Item = as === "ul" ? "li" : "div";
   return (
-    <ul
+    <List
+      // A `div` takes `group`: a name on a role-less div is one ARIA forbids and
+      // screen readers drop, and the name is what says these marks are a key.
+      role={as === "div" ? "group" : undefined}
       aria-label={ariaLabel ?? labels.legend}
       className={cn(
         "m-0 flex list-none gap-x-3 gap-y-1 p-0",
@@ -235,7 +252,7 @@ export function StaticLegend({
       )}
     >
       {entries.map((entry) => (
-        <li
+        <Item
           key={entry.key}
           className={cn(
             "flex items-center gap-1.5 text-[11px] text-[var(--text-secondary)]",
@@ -244,9 +261,9 @@ export function StaticLegend({
         >
           <LegendMark entry={entry} off={false} />
           {entry.label}
-        </li>
+        </Item>
       ))}
-    </ul>
+    </List>
   );
 }