@eifi1/ui-kit 0.15.4 → 0.16.0

package/src/components/passkeys-setting.tsx

@@ -8,9 +8,18 @@ import { Skeleton } from "./skeleton";
 import { useAccountSettingsLabels } from "./account-settings-labels";
 import type { PasskeysSettingLabels } from "./account-settings-labels";
 
-/** One registered passkey, as the app's API lists it. */
-export interface PasskeyItem {
-  id: string | number;
+/** What a passkey's `id` may be: the app's own key type, string or numeric. */
+export type PasskeyId = string | number;
+
+/**
+ * One registered passkey, as the app's API lists it.
+ *
+ * Generic in its `id` (0.16.0): `PasskeysSetting` infers `Id` from `passkeys`, so an
+ * app whose ids are numbers gets numbers back in `onRename` / `onDelete` — keksdose
+ * cast `id as number` in both. Left unparameterised it is the old `string | number`.
+ */
+export interface PasskeyItem<Id extends PasskeyId = PasskeyId> {
+  id: Id;
   name: string;
   /** A `Date`, an ISO string or epoch ms. */
   createdAt?: Date | string | number | null;
@@ -18,9 +27,12 @@ export interface PasskeyItem {
   lastUsedAt?: Date | string | number | null;
 }
 
-export interface PasskeysSettingProps {
+/** `data-*` attributes, passed through to the element they are given for. */
+export type PasskeyDataAttributes = { [key: `data-${string}`]: string | number | boolean | undefined };
+
+export interface PasskeysSettingProps<Id extends PasskeyId = PasskeyId> extends PasskeyDataAttributes {
   /** `undefined` while the first load is in flight (or pass `loading`). */
-  passkeys: readonly PasskeyItem[] | undefined;
+  passkeys: readonly PasskeyItem<Id>[] | undefined;
   loading?: boolean;
   /**
    * Run the WebAuthn ceremony and register the passkey — app-side, since the options
@@ -33,11 +45,11 @@ export interface PasskeysSettingProps {
   /** The ceremony is running. The add button says so and does not start a second one. */
   adding?: boolean;
   /** Offer "Rename" on each row. Return a promise to leave edit mode only on success. */
-  onRename?: (id: PasskeyItem["id"], name: string) => void | Promise<unknown>;
+  onRename?: (id: Id, name: string) => void | Promise<unknown>;
   /** Offer "Delete" on each row — always behind an inline confirmation. */
-  onDelete?: (id: PasskeyItem["id"]) => void | Promise<unknown>;
+  onDelete?: (id: Id) => void | Promise<unknown>;
   /** A row whose rename or delete is in flight; its buttons are disabled. */
-  busyId?: PasskeyItem["id"] | null;
+  busyId?: Id | null;
   /** Show the name field above the add button. Default true. */
   nameField?: boolean;
   /**
@@ -53,6 +65,12 @@ export interface PasskeysSettingProps {
   /** Prop > `<UiKitProvider labels={{ accountSettings: { passkeys } }}>` > English. */
   labels?: Partial<PasskeysSettingLabels>;
   className?: string;
+  /** On the card (0.16.0), for an in-page link (`#passkeys`) or a test hook. `data-*`
+   *  attributes go there too. */
+  id?: string;
+  /** Extra attributes for one row's `<li>` (0.16.0) — an `id` to scroll a just-added
+   *  key into view, `data-*` for a test. Every row also carries `data-passkey-id`. */
+  rowProps?: (item: PasskeyItem<Id>) => ({ id?: string } & PasskeyDataAttributes) | undefined;
 }
 
 /**
@@ -70,7 +88,7 @@ export interface PasskeysSettingProps {
  * the passkey it names. Focus moves to Cancel, as in every destructive confirm in the
  * kit, so the Enter that pressed Delete cannot also answer it.
  */
-export function PasskeysSetting({
+export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
   passkeys,
   loading,
   onAdd,
@@ -84,7 +102,9 @@ export function PasskeysSetting({
   locale: localeProp,
   labels: labelsProp,
   className,
-}: PasskeysSettingProps) {
+  rowProps,
+  ...rest
+}: PasskeysSettingProps<Id>) {
   const labels = useAccountSettingsLabels("passkeys", labelsProp);
   const locale = useKitLocale(localeProp);
   const [name, setName] = useState("");
@@ -126,6 +146,7 @@ export function PasskeysSetting({
                 item={item}
                 created={date(item.createdAt)}
                 lastUsed={date(item.lastUsedAt)}
+                attributes={rowProps?.(item)}
                 busy={busyId !== undefined && busyId !== null && busyId === item.id}
                 onRename={onRename}
                 onDelete={onDelete}
@@ -160,7 +181,8 @@ export function PasskeysSetting({
   })();
 
   return (
-    <Card className={cn("p-4 space-y-3", className)}>
+    // `rest` is only `id` and `data-*`: everything else the props name is destructured.
+    <Card {...rest} className={cn("p-4 space-y-3", className)}>
       <div>
         <div className="text-sm font-medium">{labels.title}</div>
         <div className="text-xs text-[var(--text-muted)]">
@@ -174,21 +196,23 @@ export function PasskeysSetting({
 
 type RowMode = "view" | "rename" | "delete";
 
-function PasskeyRow({
+function PasskeyRow<Id extends PasskeyId>({
   item,
   created,
   lastUsed,
+  attributes,
   busy,
   onRename,
   onDelete,
   labels,
 }: {
-  item: PasskeyItem;
+  item: PasskeyItem<Id>;
   created: string | null;
   lastUsed: string | null;
+  attributes?: { id?: string } & PasskeyDataAttributes;
   busy: boolean;
-  onRename?: PasskeysSettingProps["onRename"];
-  onDelete?: PasskeysSettingProps["onDelete"];
+  onRename?: PasskeysSettingProps<Id>["onRename"];
+  onDelete?: PasskeysSettingProps<Id>["onDelete"];
   labels: PasskeysSettingLabels;
 }) {
   const [mode, setMode] = useState<RowMode>("view");
@@ -241,13 +265,16 @@ function PasskeyRow({
       .catch(() => {});
   };
 
+  // On every mode's <li>, so an id the app scrolls to survives a rename or a confirm.
+  const li = { ...attributes, "data-passkey-id": String(item.id) };
+
   const meta = [created && labels.created(created), lastUsed ? labels.lastUsed(lastUsed) : labels.neverUsed]
     .filter(Boolean)
     .join(" · ");
 
   if (mode === "rename") {
     return (
-      <li className="flex flex-wrap items-center gap-2 py-2">
+      <li {...li} className="flex flex-wrap items-center gap-2 py-2">
         <Input
           ref={renameRef}
           aria-label={labels.renameField(item.name)}
@@ -278,7 +305,7 @@ function PasskeyRow({
 
   if (mode === "delete") {
     return (
-      <li className="space-y-2 py-2">
+      <li {...li} className="space-y-2 py-2">
         <p role="alert" className="text-sm">
           {labels.deleteConfirm(item.name)}
         </p>
@@ -295,7 +322,7 @@ function PasskeyRow({
   }
 
   return (
-    <li className="flex items-center gap-3 py-2">
+    <li {...li} className="flex items-center gap-3 py-2">
       <KeyRound className="size-4 shrink-0 text-[var(--text-muted)]" aria-hidden />
       <div className="min-w-0 flex-1">
         <div className="truncate text-sm font-medium">{item.name}</div>

package/src/components/progress-bar.tsx

@@ -105,6 +105,12 @@ export interface ProgressBarSegment {
 }
 
 export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "role"> {
+  /**
+   * `"span"` builds the bar from spans, for a place only phrasing content may go: inside
+   * a button or a link (ListItem's `content`). The `legend` stays a list, so leave it off
+   * there. Default `"div"`.
+   */
+  as?: "div" | "span";
   /** 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). */
   value?: number;
@@ -155,8 +161,11 @@ export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">,
   legend?: boolean;
   /**
    * What a legend row shows at its end, in place of the part's formatted value — which
-   * it is handed, with the segment and its index. keksdose's cut card shows the share
-   * AND a private outflow amount per bucket (cut-card:150), which one figure could not:
+   * it is handed, with the segment and its index. That value is the part's OWN, signed
+   * and unclamped (`formatValue`, or a percentage of the scale): a part of −40 on a
+   * 0–100 scale says "-40%" though the bar draws nothing for it. keksdose's cut card
+   * shows the share AND a private outflow amount per bucket (cut-card:150), which one
+   * figure could not:
    * `legendValue={(seg, share) => <>{share} <Amount … /></>}`.
    */
   legendValue?: (segment: ProgressBarSegment, formatted: string, index: number) => ReactNode;
@@ -209,11 +218,17 @@ export function ProgressBar({
   overage,
   labels,
   className,
+  as = "div",
   "aria-label": ariaLabel,
   "aria-labelledby": ariaLabelledBy,
   "aria-describedby": ariaDescribedBy,
   ...rest
 }: ProgressBarProps) {
+  // `as="span"`: the same bar from phrasing elements only, so it is valid inside a
+  // <button> or <a> — ListItem's `content` puts a budget bar inside the row's target
+  // (keksdose P2). Every span is made a block except those already laid out as flex.
+  const Tag = as;
+  const inlineClass = as === "span" ? "block [&_span:not(.flex):not(.inline-flex)]:block" : undefined;
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
   const text = useKitLabels("progressBar", DEFAULT_PROGRESS_BAR_LABELS, labels);
   const kitLocale = useKitLocale(locale);
@@ -236,8 +251,8 @@ export function ProgressBar({
           ? formatValue(value, Infinity, min)
           : new Intl.NumberFormat(kitLocale).format(value);
     return (
-      <div {...rest} className={cn("min-w-0", className)} data-state="unlimited">
-        <div className="flex items-baseline gap-2 text-sm">
+      <Tag {...rest} className={cn("min-w-0", inlineClass, className)} data-state="unlimited">
+        <Tag className="flex items-baseline gap-2 text-sm">
           {label != null && (
             <span id={labelId} className="min-w-0 text-[var(--text-secondary)]">
               {label}
@@ -247,9 +262,9 @@ export function ProgressBar({
             {shown !== undefined && `${shown} · `}
             {text.unlimited}
           </span>
-        </div>
+        </Tag>
         {hintNode}
-      </div>
+      </Tag>
     );
   }
   const max = maxProp;
@@ -269,9 +284,21 @@ export function ProgressBar({
       : new Intl.NumberFormat(kitLocale, { style: "percent", maximumFractionDigits: 0 }).format(
           span <= 0 ? 0 : (Math.min(max, Math.max(min, v)) - min) / span,
         );
+  // A PART is stated as its own value, sign and all — not as the slice of track it
+  // draws. The bar cannot draw a negative part (a refund inside a month's spending) or
+  // one past `max`, but the legend and the reader can still say it: before 0.16 a
+  // −CHF 40 part read "0 %" in both, and keksdose had to pass `legendValue` just to get
+  // the minus back. For a part inside `min`–`max` this is the same text as before.
+  const formatPart = (v: number) => {
+    if (!Number.isFinite(v)) return format(min);
+    if (formatValue) return formatValue(v, max, min);
+    return new Intl.NumberFormat(kitLocale, { style: "percent", maximumFractionDigits: 0 }).format(
+      span <= 0 ? 0 : (v - min) / span,
+    );
+  };
   const partTexts = stacked
     ? barParts.map((seg) => {
-        const text = format(min + partValue(seg.value));
+        const text = formatPart(seg.value);
         return typeof seg.label === "string" || typeof seg.label === "number"
           ? common.fieldValue(String(seg.label), text)
           : text;
@@ -306,9 +333,9 @@ export function ProgressBar({
   const name = labelledBy ? undefined : (ariaLabel ?? (indeterminate ? common.loading : undefined));
 
   return (
-    <div className={cn("min-w-0", className)} data-state={indeterminate ? "indeterminate" : "determinate"}>
+    <Tag className={cn("min-w-0", inlineClass, className)} data-state={indeterminate ? "indeterminate" : "determinate"}>
       {(label != null || (showValue && valueText !== undefined)) && (
-        <div className="mb-1 flex items-baseline gap-2 text-sm">
+        <Tag className="mb-1 flex items-baseline gap-2 text-sm">
           {label != null && (
             <span id={labelId} className="min-w-0 text-[var(--text-secondary)]">
               {label}
@@ -321,9 +348,9 @@ export function ProgressBar({
               {valueText}
             </span>
           )}
-        </div>
+        </Tag>
       )}
-      <div
+      <Tag
         {...rest}
         role={meter ? "meter" : "progressbar"}
         aria-label={name}
@@ -341,10 +368,10 @@ export function ProgressBar({
         {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">
+          <Tag className="flex h-full w-full gap-0.5">
             {segments.map((seg, i) =>
               seg.legendOnly ? null : (
-                <div
+                <Tag
                   key={seg.key ?? i}
                   data-part="segment"
                   className={cn(
@@ -358,9 +385,9 @@ export function ProgressBar({
                 />
               ),
             )}
-          </div>
+          </Tag>
         ) : indeterminate ? (
-          <div
+          <Tag
             data-part="fill"
             className={cn(
               // `left-0`, deliberately physical: the keyframes (tokens.css
@@ -375,7 +402,7 @@ export function ProgressBar({
             )}
           />
         ) : (
-          <div
+          <Tag
             data-part="fill"
             // Block flow starts at the inline start, so a plain width fills from the
             // right under `dir="rtl"` with nothing extra.
@@ -383,7 +410,7 @@ export function ProgressBar({
             style={{ width: `${fraction * 100}%` }}
           />
         )}
-      </div>
+      </Tag>
       {stacked && legend && segments.length > 0 && (
         <ul className="mt-2 space-y-1 text-sm" data-part="legend">
           {segments.map((seg, i) => (
@@ -400,9 +427,7 @@ export function ProgressBar({
                 <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)]">
-                {legendValue
-                  ? legendValue(seg, format(min + partValue(seg.value)), i)
-                  : format(min + partValue(seg.value))}
+                {legendValue ? legendValue(seg, formatPart(seg.value), i) : formatPart(seg.value)}
               </span>
             </li>
           ))}
@@ -410,6 +435,6 @@ export function ProgressBar({
       )}
       {overageNode}
       {hintNode}
-    </div>
+    </Tag>
   );
 }

package/src/components/signed-amount.tsx

@@ -78,6 +78,17 @@ export type GoodDirection = "up" | "down";
  */
 export type SignedAmountTone = "signed" | "income" | "expense" | "neutral" | "verdict";
 
+/**
+ * The colours a VERDICT is painted in (`goodDirection` set, or `tone="verdict"`):
+ *  - `status` (default) — `success` / `danger`: good news, bad news.
+ *  - `money` — `income` / `expense` (the `.text-money-pos` / `.text-money-neg` pair):
+ *    the app's ONE money palette (keksdose dev#434). A grocery price going UP is money
+ *    going out, so with `goodDirection="down"` it wears the expense colour every other
+ *    outflow in the app wears — not a red that says "error". keksdose coloured its
+ *    three price-change sites by hand for want of this.
+ */
+export type VerdictPalette = "status" | "money";
+
 /** What a signed figure says to a screen reader, whose readers disagree about a
  *  leading "+" (most skip it) and a "−" (some read "dash", some nothing). */
 export interface SignedAmountLabels {
@@ -117,18 +128,28 @@ function useMagnitudeFormatter({ currency, unit, compact, digits, format, locale
   };
 }
 
-function directionOf(value: number): "up" | "down" | "flat" {
-  return value > 0 ? "up" : value < 0 ? "down" : "flat";
+/** `flatWithin` widens "no change" from exactly zero to a band round it: a price that
+ *  moved by a fraction of a cent, a ratio that rounds to "0.0 %", is not a rise, and an
+ *  arrow and a colour for it claim one. Inclusive — `|value| ≤ flatWithin` is flat. */
+function directionOf(value: number, flatWithin = 0): "up" | "down" | "flat" {
+  if (Math.abs(value) <= Math.max(0, flatWithin)) return "flat";
+  return value > 0 ? "up" : "down";
+}
+
+function verdictClass(good: boolean, palette: VerdictPalette): string {
+  if (palette === "money") return good ? TEXT_TONE.income : TEXT_TONE.expense;
+  return good ? TEXT_TONE.success : TEXT_TONE.danger;
 }
 
 function signedToneClass(
   tone: SignedAmountTone,
   dir: "up" | "down" | "flat",
   goodDirection: GoodDirection | undefined,
+  palette: VerdictPalette,
 ): string {
   if (tone === "verdict" || (goodDirection && tone === "signed")) {
     if (dir === "flat" || !goodDirection) return TEXT_TONE.muted;
-    return dir === goodDirection ? TEXT_TONE.success : TEXT_TONE.danger;
+    return verdictClass(dir === goodDirection, palette);
   }
   if (tone === "signed") return dir === "flat" ? TEXT_TONE.muted : dir === "up" ? TEXT_TONE.income : TEXT_TONE.expense;
   if (tone === "neutral") return "";
@@ -143,8 +164,16 @@ export interface SignedAmountProps
   value: number;
   /** See {@link SignedAmountTone}. Default `signed`, or `verdict` with `goodDirection`. */
   tone?: SignedAmountTone;
-  /** Which way is good news — colours by verdict (`success` / `danger`). */
+  /** Which way is good news — colours by verdict (`success` / `danger`, or the money
+   *  pair with `palette="money"`). */
   goodDirection?: GoodDirection;
+  /** See {@link VerdictPalette}. Default `status`. Only a verdict reads it. */
+  palette?: VerdictPalette;
+  /** A magnitude up to which the figure counts as NO change: no sign, no arrow but the
+   *  flat dash, muted, spoken without "plus"/"minus" (inclusive; default 0). The digits
+   *  still print `|value|` — use a band below the display precision, where they round
+   *  to zero anyway (`flatWithin={0.005}` at two digits). */
+  flatWithin?: number;
   /** Print "+" before a positive figure (default `true`). A negative always shows its
    *  minus; zero shows neither. */
   showPlus?: boolean;
@@ -177,6 +206,8 @@ export function SignedAmount({
   locale,
   tone = "signed",
   goodDirection,
+  palette = "status",
+  flatWithin,
   showPlus = true,
   arrow = false,
   sensitive = false,
@@ -187,7 +218,7 @@ export function SignedAmount({
   const text = useKitLabels("signedAmount", DEFAULT_SIGNED_AMOUNT_LABELS, labels);
   const fmt = useMagnitudeFormatter({ currency, unit, compact, digits, format, locale });
   const finite = Number.isFinite(value);
-  const dir = finite ? directionOf(value) : "flat";
+  const dir = finite ? directionOf(value, flatWithin) : "flat";
   const amount = finite ? fmt(Math.abs(value)) : "—";
   // U+2212, the typographic minus: the same width as "+", so a column of signed figures
   // lines up under `tabular-nums`.
@@ -201,7 +232,7 @@ export function SignedAmount({
       data-direction={dir}
       className={cn(
         "relative inline-flex items-center gap-0.5 whitespace-nowrap tabular-nums",
-        signedToneClass(tone, dir, goodDirection),
+        signedToneClass(tone, dir, goodDirection, palette),
         className,
       )}
     >
@@ -221,6 +252,12 @@ export interface DeltaProps extends SignedFormatProps, Omit<ComponentPropsWithou
   /** Which way is good news. Unset, the change is stated and not judged (muted); set,
    *  it is coloured `success` / `danger` and its sentence says "(better)" / "(worse)". */
   goodDirection?: GoodDirection;
+  /** See {@link VerdictPalette}: `money` paints good news `income` and bad news
+   *  `expense` instead of `success` / `danger`. Default `status`. */
+  palette?: VerdictPalette;
+  /** See {@link SignedAmountProps.flatWithin}: up to this magnitude the change is
+   *  "unchanged" — flat dash, muted, no verdict. Default 0. */
+  flatWithin?: number;
   /** What it is measured against, after it: "vs last month". */
   label?: ReactNode;
   /** Hide the arrow (shown by default, as on a StatTile). At zero the arrow is a flat
@@ -249,6 +286,8 @@ export function Delta({
   format,
   locale,
   goodDirection,
+  palette = "status",
+  flatWithin,
   label,
   arrow = true,
   sensitive = false,
@@ -260,14 +299,14 @@ export function Delta({
   const fmt = useMagnitudeFormatter({ currency, unit, compact, digits, format, locale });
   if (!Number.isFinite(value)) return null;
   const amount = fmt(Math.abs(value));
-  const dir = directionOf(value);
+  const dir = directionOf(value, flatWithin);
   const Icon = ARROW[dir];
   let spoken = dir === "up" ? text.increase(amount) : dir === "down" ? text.decrease(amount) : text.unchanged;
   let tone = TEXT_TONE.muted;
   if (goodDirection && dir !== "flat") {
     const good = dir === goodDirection;
     spoken = good ? text.better(spoken) : text.worse(spoken);
-    tone = good ? TEXT_TONE.success : TEXT_TONE.danger;
+    tone = verdictClass(good, palette);
   }
   return (
     <span

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. */