@eifi1/ui-kit 0.11.0 → 0.13.0

package/src/components/progress-bar.tsx

@@ -3,6 +3,19 @@ import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels";
 
+/** The words a progress bar adds of its own. */
+export interface ProgressBarLabels {
+  /** Shown after the value when `max={null}`: a quota with no ceiling. */
+  unlimited: string;
+  /** The `overage` line: how far past `max` the value is. `amount` is formatted. */
+  overLimit: (amount: string) => string;
+}
+
+export const DEFAULT_PROGRESS_BAR_LABELS: ProgressBarLabels = {
+  unlimited: "Unlimited",
+  overLimit: (amount) => `${amount} over the limit`,
+};
+
 /**
  * `income` / `expense` are the money pair (`--money-income` / `--money-expense`), the
  * names `Chip`, `StatTile` and `Sparkline` already use for them: a share bar of what
@@ -82,6 +95,13 @@ export interface ProgressBarSegment {
   label?: ReactNode;
   /** A stable React key, when `label` is not a string. */
   key?: string;
+  /**
+   * List it in the `legend` but leave it out of the bar — its value, its share of the
+   * `aria-valuetext`, and the sum. keksdose's cut card (reports/cut-card:132) names
+   * EVERY bucket under its bar, the empty ones included, while the bar draws only the
+   * ones with a share: pass the empty buckets as `legendOnly` entries.
+   */
+  legendOnly?: boolean;
 }
 
 export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "role"> {
@@ -89,7 +109,14 @@ export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">,
    *  and nobody knows how much is left (an import that reports no count). */
   value?: number;
   min?: number;
-  max?: number;
+  /**
+   * The top of the scale (default 100). `null` is a quota with NO ceiling — kastlan's
+   * billing usage on an unlimited plan (usage-progress-bar:25): nothing to fill, so no
+   * bar is drawn; the label row shows the value and "Unlimited" (`progressBar.unlimited`)
+   * as plain text. `formatValue` is then called with `max` = `Infinity`; without it,
+   * the value is a plain number in the kit's locale.
+   */
+  max?: number | null;
   /**
    * `progress` (default): a task moving toward completion — `role="progressbar"`.
    * `meter`: a share of a known whole that is not going anywhere (budget used, disk
@@ -126,6 +153,25 @@ export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">,
   /** 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;
+  /**
+   * 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:
+   * `legendValue={(seg, share) => <>{share} <Amount … /></>}`.
+   */
+  legendValue?: (segment: ProgressBarSegment, formatted: string, index: number) => ReactNode;
+  /** A muted line under the bar — the plan's reset date, "3 of 5 seats in use". It
+   *  describes the bar (`aria-describedby`). */
+  hint?: ReactNode;
+  /**
+   * When `value` is past `max`, say by how much, in a danger-coloured line under the bar
+   * (kastlan usage-progress-bar:46): `true` prints `progressBar.overLimit` with the
+   * excess as a plain number; a function renders the line itself from the excess (a
+   * currency, "2 seats"). The bar stays full at `max` either way — colour it with
+   * `tone="danger"` if it should read as over. Ignored for `segments` and `max={null}`.
+   */
+  overage?: boolean | ((over: number) => ReactNode);
+  labels?: Partial<ProgressBarLabels>;
 }
 
 /**
@@ -148,7 +194,7 @@ export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">,
 export function ProgressBar({
   value,
   min = 0,
-  max = 100,
+  max: maxProp = 100,
   variant = "progress",
   label,
   showValue = false,
@@ -158,21 +204,65 @@ export function ProgressBar({
   locale,
   segments,
   legend = false,
+  legendValue,
+  hint,
+  overage,
+  labels,
   className,
   "aria-label": ariaLabel,
   "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy,
   ...rest
 }: ProgressBarProps) {
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const text = useKitLabels("progressBar", DEFAULT_PROGRESS_BAR_LABELS, labels);
   const kitLocale = useKitLocale(locale);
   const labelId = useId();
+  const hintId = useId();
+  const hintNode =
+    hint != null ? (
+      <p id={hintId} data-part="hint" className="mt-1 text-xs text-[var(--text-muted)]">
+        {hint}
+      </p>
+    ) : null;
+
+  if (maxProp === null) {
+    // No ceiling: no bar, no role — a meter with no maximum is not one. The value and
+    // "Unlimited" are the content, so they are plain visible text.
+    const shown =
+      value === undefined || !Number.isFinite(value)
+        ? undefined
+        : formatValue
+          ? 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">
+          {label != null && (
+            <span id={labelId} className="min-w-0 text-[var(--text-secondary)]">
+              {label}
+            </span>
+          )}
+          <span data-part="unlimited" className="ms-auto shrink-0 tabular-nums text-[var(--text-muted)]">
+            {shown !== undefined && `${shown} · `}
+            {text.unlimited}
+          </span>
+        </div>
+        {hintNode}
+      </div>
+    );
+  }
+  const max = maxProp;
 
   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);
+  // Colours are dealt over EVERY segment, legend-only ones included, so an entry keeps
+  // its swatch whether or not it is in the bar this time.
   const fills = stacked ? segmentFills(segments) : [];
-  const partTotal = stacked ? min + segments.reduce((sum, seg) => sum + partValue(seg.value), 0) : undefined;
+  const barParts = stacked ? segments.filter((seg) => !seg.legendOnly) : [];
+  const partTotal = stacked ? min + barParts.reduce((sum, seg) => sum + partValue(seg.value), 0) : undefined;
   const format = (v: number) =>
     formatValue
       ? formatValue(v, max, min)
@@ -180,7 +270,7 @@ export function ProgressBar({
           span <= 0 ? 0 : (Math.min(max, Math.max(min, v)) - min) / span,
         );
   const partTexts = stacked
-    ? segments.map((seg) => {
+    ? barParts.map((seg) => {
         const text = format(min + partValue(seg.value));
         return typeof seg.label === "string" || typeof seg.label === "number"
           ? common.fieldValue(String(seg.label), text)
@@ -199,6 +289,19 @@ export function ProgressBar({
       ? new Intl.ListFormat(kitLocale, { style: "short", type: "unit" }).format(partTexts)
       : valueText;
 
+  const over =
+    overage && !stacked && value !== undefined && Number.isFinite(value) && value > max ? value - max : 0;
+  const overageNode =
+    over > 0 ? (
+      <p id={`${hintId}-over`} data-part="overage" className="mt-1 text-xs text-[var(--danger)]">
+        {typeof overage === "function"
+          ? overage(over)
+          : text.overLimit(new Intl.NumberFormat(kitLocale).format(over))}
+      </p>
+    ) : null;
+  const describedBy =
+    [ariaDescribedBy, hintNode && hintId, overageNode && `${hintId}-over`].filter(Boolean).join(" ") || undefined;
+
   const labelledBy = ariaLabelledBy ?? (label != null ? labelId : undefined);
   const name = labelledBy ? undefined : (ariaLabel ?? (indeterminate ? common.loading : undefined));
 
@@ -225,6 +328,7 @@ export function ProgressBar({
         role={meter ? "meter" : "progressbar"}
         aria-label={name}
         aria-labelledby={labelledBy}
+        aria-describedby={describedBy}
         aria-valuemin={indeterminate ? undefined : min}
         aria-valuemax={indeterminate ? undefined : max}
         aria-valuenow={clamped}
@@ -238,20 +342,22 @@ export function ProgressBar({
           // 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,
-                }}
-              />
-            ))}
+            {segments.map((seg, i) =>
+              seg.legendOnly ? null : (
+                <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
@@ -294,12 +400,16 @@ 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)]">
-                {format(min + partValue(seg.value))}
+                {legendValue
+                  ? legendValue(seg, format(min + partValue(seg.value)), i)
+                  : format(min + partValue(seg.value))}
               </span>
             </li>
           ))}
         </ul>
       )}
+      {overageNode}
+      {hintNode}
     </div>
   );
 }

package/src/components/qr-code.tsx

@@ -0,0 +1,83 @@
+import { useMemo } from "react";
+import type { ComponentPropsWithoutRef } from "react";
+import { cn } from "../lib/cn";
+import { encodeQr } from "../lib/qr-encode";
+import type { QrErrorCorrection } from "../lib/qr-encode";
+
+export interface QrCodeProps extends Omit<ComponentPropsWithoutRef<"svg">, "children" | "viewBox"> {
+  /** The text to encode (UTF-8) — an `otpauth://` URI, a URL, a pairing code. */
+  value: string;
+  /** The accessible name. Without it the code is decorative (`aria-hidden`): say what
+   *  it is for, not what it encodes — nobody wants a URI read out. */
+  label?: string;
+  /** Default `"M"`, raised automatically where the size allows it. */
+  errorCorrection?: QrErrorCorrection;
+  /** The quiet zone, in modules. The spec asks for 4; less reads worse. Default 4. */
+  margin?: number;
+}
+
+/**
+ * A QR code as one inline SVG — no canvas, no data URL, no dependency (see
+ * `lib/qr-encode.ts` for why the encoder lives in the kit).
+ *
+ * Sized by CSS (`className="size-48"`); the SVG scales without blurring because every
+ * module is a whole unit of the viewBox and `shape-rendering` is `crispEdges`.
+ *
+ * **Black on white, always — the one literal colour pair in the kit.** A camera looks
+ * for the contrast between the modules and their quiet zone; on the dark theme a
+ * surface-coloured background makes a code slow to acquire, and an inverted one is not
+ * read at all by several authenticator apps. The quiet zone is part of the SVG, so the
+ * code carries its own white border wherever it is placed.
+ *
+ * A value too long for any QR version (≈2.9 kB) renders nothing rather than throwing
+ * in render.
+ */
+export function QrCode({
+  value,
+  label,
+  errorCorrection = "M",
+  margin = 4,
+  className,
+  ...rest
+}: QrCodeProps) {
+  const path = useMemo(() => {
+    try {
+      const { modules, size } = encodeQr(value, { errorCorrection });
+      // One path, one sub-path per horizontal run of dark modules: a few hundred
+      // commands rather than one <rect> per module.
+      let d = "";
+      for (let y = 0; y < size; y++) {
+        for (let x = 0; x < size; ) {
+          if (!modules[y][x]) {
+            x++;
+            continue;
+          }
+          let run = 1;
+          while (x + run < size && modules[y][x + run]) run++;
+          d += `M${x + margin} ${y + margin}h${run}v1h-${run}z`;
+          x += run;
+        }
+      }
+      return { d, extent: size + margin * 2 };
+    } catch {
+      return null;
+    }
+  }, [value, errorCorrection, margin]);
+
+  if (!path) return null;
+  return (
+    <svg
+      {...rest}
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox={`0 0 ${path.extent} ${path.extent}`}
+      shapeRendering="crispEdges"
+      role={label ? "img" : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
+      className={cn("block", className)}
+    >
+      <rect width={path.extent} height={path.extent} fill="#ffffff" />
+      <path d={path.d} fill="#000000" />
+    </svg>
+  );
+}

package/src/components/search-field.tsx

@@ -3,6 +3,7 @@ import type { InputHTMLAttributes } from "react";
 import { Search, X } from "lucide-react";
 import { cn } from "../lib/cn";
 import { FIELD_BASE } from "./ui";
+import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
 
 interface SearchFieldOwnProps
   extends Omit<
@@ -23,10 +24,22 @@ interface SearchFieldOwnProps
    * absent, so a consumer can migrate one call site at a time.
    */
   label?: string;
-  /** Names the clear button. Omit it and no clear button is rendered — which is a
-   *  decision, not a default: a filter you can type into and not untype is the
-   *  complaint that produced the button on three of these four screens. */
+  /** Names the clear button. Default: the catalogue's `common.clear`, in the
+   *  provider's language. */
   clearLabel?: string;
+  /**
+   * Draw the "×" that empties the field once there is something in it. Default
+   * `true`.
+   *
+   * It used to appear only when a `clearLabel` was passed, and every kastlan call
+   * site passed one — lease-list-page.tsx:91, trial-balance-page.tsx:~196,
+   * account-ledger-page.tsx:~131 and data-table/resource-list-page.tsx:256 each
+   * spelled `clearLabel={t("table.clear")}` — so the opt-in was boilerplate: a filter
+   * you can type into and not untype is the complaint that produced the button in
+   * the first place, and the catalogue already names it. `false` is for a field
+   * whose clearing lives elsewhere (a "Reset filters" beside it).
+   */
+  clearable?: boolean;
   /**
    * `"field"` (default): the bordered filter box that sits on a page.
    *
@@ -96,7 +109,8 @@ export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(functi
     value,
     onChange,
     label,
-    clearLabel,
+    clearLabel: clearLabelProp,
+    clearable = true,
     className,
     inputClassName,
     placeholder,
@@ -107,6 +121,8 @@ export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(functi
   ref,
 ) {
   const innerRef = useRef<HTMLInputElement>(null);
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const clearLabel = clearable ? (clearLabelProp ?? common.clear) : undefined;
   // Whichever spelling the caller used. It is the accessible name AND the placeholder
   // fallback, so a box named only by `aria-label` still says what it is before anyone
   // has typed in it — the same deal `label` has always had.

package/src/components/signed-amount.tsx

@@ -0,0 +1,295 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { ArrowDown, ArrowUp, Minus } from "lucide-react";
+import { cn } from "../lib/cn";
+import { formatMoney, formatNumber, formatPercent } from "../lib/format";
+import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { DEFAULT_STAT_TILE_LABELS } from "./stat-tile";
+import type { StatTileLabels } from "./stat-tile";
+
+/**
+ * The text colours a figure can carry, token-backed — `StatTile`'s tones, as a class
+ * any span can take.
+ *
+ *  - `default` — the primary text colour. `muted` — the secondary, quiet one.
+ *  - `income` / `expense` / `net` — the money trio (CVD-safe teal / amber / violet).
+ *  - `success` / `warning` / `danger` / `info` — a verdict: a rent rise is the tenant's
+ *    bad news (kastlan lease-columns), a vote "for" is green (meeting-agenda-tab).
+ *  - `brand` — the app's accent.
+ *
+ * Colour is never the only carrier: pair a verdict with an arrow, a word, or a sign.
+ */
+export type TextTone =
+  | "default"
+  | "muted"
+  | "brand"
+  | "income"
+  | "expense"
+  | "net"
+  | "success"
+  | "warning"
+  | "danger"
+  | "info";
+
+const TEXT_TONE: Record<TextTone, string> = {
+  default: "text-[var(--text-primary)]",
+  muted: "text-[var(--text-muted)]",
+  brand: "text-[var(--brand)]",
+  income: "text-[var(--money-income)]",
+  expense: "text-[var(--money-expense)]",
+  net: "text-[var(--money-net)]",
+  success: "text-[var(--success)]",
+  warning: "text-[var(--warning)]",
+  danger: "text-[var(--danger)]",
+  info: "text-[var(--info)]",
+};
+
+/**
+ * The class that colours text in `tone` — for the spans kastlan colours by hand with
+ * `text-[var(--danger)]` / `text-emerald-600` (settlement-table, changelog-page,
+ * meeting-agenda-tab), so the palette they draw from is the kit's tokens.
+ */
+export function toneTextClass(tone: TextTone): string {
+  return TEXT_TONE[tone];
+}
+
+export interface ToneProps extends ComponentPropsWithoutRef<"span"> {
+  tone: TextTone;
+}
+
+/** A `<span>` in a {@link TextTone} — `<Tone tone="success">{votesFor}</Tone>`. */
+export function Tone({ tone, className, ...rest }: ToneProps) {
+  return <span {...rest} className={cn(TEXT_TONE[tone], className)} />;
+}
+
+/* ── Signed amounts ──────────────────────────────────────────────────────── */
+
+/** Which way is +1: `up` for a figure where more is good news (income, savings),
+ *  `down` where less is (a rent the tenant pays, a cost). */
+export type GoodDirection = "up" | "down";
+
+/**
+ * How a signed figure is coloured:
+ *  - `signed` (default) — money read by its own sign: above zero `income`, below zero
+ *    `expense`, zero muted. A balance, a net.
+ *  - `income` / `expense` / `neutral` — one colour whatever the sign (`neutral` is the
+ *    text's own colour).
+ *  - `verdict` — the change judged by {@link SignedAmountProps.goodDirection}: good
+ *    news `success`, bad news `danger`, zero muted. Setting `goodDirection` implies it.
+ */
+export type SignedAmountTone = "signed" | "income" | "expense" | "neutral" | "verdict";
+
+/** 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 {
+  /** A figure above zero. `amount` is formatted and unsigned. */
+  positive: (amount: string) => string;
+  /** A figure below zero. `amount` is formatted and unsigned. */
+  negative: (amount: string) => string;
+}
+
+export const DEFAULT_SIGNED_AMOUNT_LABELS: SignedAmountLabels = {
+  positive: (amount) => `plus ${amount}`,
+  negative: (amount) => `minus ${amount}`,
+};
+
+interface SignedFormatProps {
+  /** ISO 4217 code: format as money. */
+  currency?: string;
+  /** `"percent"` reads `value` as a RATIO (`0.12` → 12 %), as `StatTile`'s delta does. */
+  unit?: "value" | "percent";
+  /** Compact notation: 12 400 → "12K". */
+  compact?: boolean;
+  /** Fraction digits, as `formatNumber`'s `digits`. */
+  digits?: number | { min?: number; max?: number };
+  /** Formats the UNSIGNED magnitude, replacing the `Intl` default outright. The sign
+   *  is the component's. */
+  format?: (magnitude: number) => string;
+  locale?: string;
+}
+
+function useMagnitudeFormatter({ currency, unit, compact, digits, format, locale }: SignedFormatProps) {
+  const kitLocale = useKitLocale(locale);
+  return (magnitude: number): string => {
+    if (format) return format(magnitude);
+    if (unit === "percent") return formatPercent(magnitude, { locale: kitLocale, compact, digits });
+    if (currency) return formatMoney(magnitude, currency, { locale: kitLocale, compact, digits });
+    return formatNumber(magnitude, { locale: kitLocale, compact, digits });
+  };
+}
+
+function directionOf(value: number): "up" | "down" | "flat" {
+  return value > 0 ? "up" : value < 0 ? "down" : "flat";
+}
+
+function signedToneClass(
+  tone: SignedAmountTone,
+  dir: "up" | "down" | "flat",
+  goodDirection: GoodDirection | undefined,
+): string {
+  if (tone === "verdict" || (goodDirection && tone === "signed")) {
+    if (dir === "flat" || !goodDirection) return TEXT_TONE.muted;
+    return dir === goodDirection ? TEXT_TONE.success : TEXT_TONE.danger;
+  }
+  if (tone === "signed") return dir === "flat" ? TEXT_TONE.muted : dir === "up" ? TEXT_TONE.income : TEXT_TONE.expense;
+  if (tone === "neutral") return "";
+  return TEXT_TONE[tone];
+}
+
+const ARROW = { up: ArrowUp, down: ArrowDown, flat: Minus } as const;
+
+export interface SignedAmountProps
+  extends SignedFormatProps,
+    Omit<ComponentPropsWithoutRef<"span">, "children"> {
+  value: number;
+  /** See {@link SignedAmountTone}. Default `signed`, or `verdict` with `goodDirection`. */
+  tone?: SignedAmountTone;
+  /** Which way is good news — colours by verdict (`success` / `danger`). */
+  goodDirection?: GoodDirection;
+  /** Print "+" before a positive figure (default `true`). A negative always shows its
+   *  minus; zero shows neither. */
+  showPlus?: boolean;
+  /** An arrow before the figure (up / down / a dash at zero) — so the direction does not
+   *  ride on colour alone. Decorative; the words say the same. */
+  arrow?: boolean;
+  /** Tag the figure `data-private`, for the host's demo-mode blur. */
+  sensitive?: boolean;
+  labels?: Partial<SignedAmountLabels>;
+}
+
+/**
+ * A figure with a sign that matters: a balance, a rent change, a net.
+ *
+ * kastlan writes it by hand in five places — `{change > 0 ? "+" : ""}{formatCurrency(
+ * change)}` in a span coloured by a ternary (lease-columns:190, settlement-table:58,
+ * the tenancy `formatPct`) — and each picks its own colours for the same verdict.
+ *
+ * The visible figure (sign, digits, arrow) is hidden from assistive tech and spoken as
+ * words instead ("plus CHF 50.00" / "minus CHF 50.00", `signedAmount.*`): a "+" is
+ * skipped by most screen readers, and `Intl`'s "−" is read as "dash" or not at all.
+ */
+export function SignedAmount({
+  value,
+  currency,
+  unit,
+  compact,
+  digits,
+  format,
+  locale,
+  tone = "signed",
+  goodDirection,
+  showPlus = true,
+  arrow = false,
+  sensitive = false,
+  labels,
+  className,
+  ...rest
+}: SignedAmountProps) {
+  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 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`.
+  const sign = dir === "up" ? (showPlus ? "+" : "") : dir === "down" ? "−" : "";
+  const spoken = dir === "up" ? text.positive(amount) : dir === "down" ? text.negative(amount) : amount;
+  const Icon = ARROW[dir];
+  return (
+    <span
+      {...rest}
+      data-private={sensitive ? "" : undefined}
+      data-direction={dir}
+      className={cn(
+        "relative inline-flex items-center gap-0.5 whitespace-nowrap tabular-nums",
+        signedToneClass(tone, dir, goodDirection),
+        className,
+      )}
+    >
+      {arrow && <Icon aria-hidden className="size-[1em] shrink-0" />}
+      <span aria-hidden>
+        {sign}
+        {amount}
+      </span>
+      <span className="sr-only">{spoken}</span>
+    </span>
+  );
+}
+
+export interface DeltaProps extends SignedFormatProps, Omit<ComponentPropsWithoutRef<"span">, "children"> {
+  /** The change. Above zero is "up". */
+  value: number;
+  /** 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;
+  /** 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
+   *  dash BESIDE the figure ("– 0.00 %"), never in place of it. */
+  arrow?: boolean;
+  sensitive?: boolean;
+  /** The `statTile` namespace's direction words — a delta says the same as a tile's. */
+  labels?: Partial<Pick<StatTileLabels, "increase" | "decrease" | "unchanged" | "better" | "worse">>;
+}
+
+/**
+ * `StatTile`'s delta on its own: an arrow, the unsigned magnitude, and a sentence for
+ * screen readers ("Up 12% (worse)"), coloured only when `goodDirection` judges it —
+ * users up and cost up are the same arrow until someone says which is good.
+ *
+ * For a change shown outside a tile: kastlan's rent-change column
+ * (lease-columns:219, a "+1.25%" chip), the breakdown rows of the rent calculator
+ * (breakdown-row:5, a trend icon coloured by hand).
+ */
+export function Delta({
+  value,
+  currency,
+  unit,
+  compact,
+  digits,
+  format,
+  locale,
+  goodDirection,
+  label,
+  arrow = true,
+  sensitive = false,
+  labels,
+  className,
+  ...rest
+}: DeltaProps) {
+  const text = useKitLabels("statTile", DEFAULT_STAT_TILE_LABELS, labels);
+  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 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;
+  }
+  return (
+    <span
+      {...rest}
+      data-direction={dir}
+      className={cn("relative inline-flex flex-wrap items-center gap-x-1.5 tabular-nums", className)}
+    >
+      <span data-private={sensitive ? "" : undefined} className={cn("inline-flex items-center gap-0.5 font-medium", tone)}>
+        {arrow && <Icon className="size-[1em] shrink-0" aria-hidden />}
+        {/* The figure at zero too, beside the flat dash (kastlan feedback #48). Before
+            this a flat delta with an arrow drew the dash ALONE, as a StatTile does — so
+            a rent-change column that printed "0.00 %" for an unchanged lease showed a
+            bare "–" in its place, and a bare dash is what a table prints for a MISSING
+            value: "unchanged" and "not known" looked the same. The Minus icon is the
+            neutral indicator, the muted tone the neutral colour, and the figure says
+            how much (none) in the column's own digits. A value that is missing never
+            reaches here — a non-finite one renders nothing, above. Visible change for
+            every `<Delta value={0}>` with the default arrow: "–" became "– 0 %". */}
+        <span aria-hidden>{amount}</span>
+        <span className="sr-only">{spoken}</span>
+      </span>
+      {label != null && <span className="text-[var(--text-muted)]">{label}</span>}
+    </span>
+  );
+}