@eifi1/ui-kit 0.16.0 → 0.17.0

package/src/components/file-button.tsx

@@ -4,6 +4,7 @@ import { cn } from "../lib/cn";
 import { useAnnounce } from "../hooks/use-announce";
 import { useKitFileLabels, useKitLabels } from "../i18n/kit-labels";
 import { Button, Spinner } from "./ui";
+import { Tooltip } from "./tooltip";
 
 /**
  * A button that opens the file picker — the shape all three apps kept writing by hand
@@ -578,17 +579,24 @@ export const FileButton = forwardRef<HTMLButtonElement, FileButtonProps>(functio
   }
   return (
     // One inline row, so the name sits beside the button wherever the button sits; the
-    // name truncates (full list in its title) rather than pushing the row wider.
+    // name truncates rather than pushing the row wider, and the full list is in the
+    // kit's own Tooltip — not a native `title` (0.16.0 shipped one: the one-tooltip rule
+    // since keksdose dev#523, and a title never opens on touch). Lazy, so the closed
+    // bubble adds nothing to the read-out's text.
     <span className="inline-flex max-w-full min-w-0 items-center gap-2">
       {button}
+      {/* The live region is the OUTER span and never remounts: a Tooltip with an empty
+          label renders no wrapper, so wrapping the region itself would swap its element
+          the moment the first file arrives — and a fresh live region may not announce. */}
       <span
         id={pickedId}
         aria-live="polite"
         data-slot="file-button-name"
-        title={picked.map((f) => f.name).join(", ") || undefined}
-        className="min-w-0 truncate text-sm text-[var(--text-secondary)]"
+        className="flex min-w-0 text-sm text-[var(--text-secondary)]"
       >
-        {pickedText}
+        <Tooltip label={picked.map((f) => f.name).join(", ")} lazy className="min-w-0">
+          <span className="block truncate">{pickedText}</span>
+        </Tooltip>
       </span>
       {picker.element}
     </span>

package/src/components/form-actions.tsx

@@ -3,6 +3,7 @@ import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
 import { useKitLabels } from "../i18n/kit-labels";
+import { useMediaQuery } from "../hooks/use-media-query";
 import { Button, Spinner, type ButtonProps, type ButtonVariant } from "./ui";
 
 /** The words {@link FormActions} renders on its own behalf — the `form` namespace. */
@@ -29,6 +30,56 @@ export type FormActionsAlign = "start" | "center" | "end" | "between";
  */
 export type FormActionsPlacement = "inline" | "sticky" | "dialog";
 
+/**
+ * A placement per breakpoint, mobile first — `{ base: "sticky", md: "inline" }` is a
+ * Save row stuck to the bottom of a phone's long form and in the flow under the last
+ * field from 768px up, where the form fits. The breakpoints are Tailwind's (sm 640,
+ * md 768, lg 1024, xl 1280px), as `BulkActionBar`'s `variant` breakpoints are, and
+ * resolved the same way, in JS: the sticky row is positioned by inline style, which a
+ * `md:` class cannot reach. keksdose switched `placement` on its own media query at
+ * every long form for want of this.
+ */
+export interface ResponsiveFormActionsPlacement {
+  base: FormActionsPlacement;
+  sm?: FormActionsPlacement;
+  md?: FormActionsPlacement;
+  lg?: FormActionsPlacement;
+  xl?: FormActionsPlacement;
+}
+
+const BREAKPOINTS = [
+  ["xl", "(min-width: 1280px)"],
+  ["lg", "(min-width: 1024px)"],
+  ["md", "(min-width: 768px)"],
+  ["sm", "(min-width: 640px)"],
+] as const;
+
+/** The placement in force: the widest breakpoint that matches AND names one, else
+ *  `base`. The queries are subscribed unconditionally (hooks cannot be skipped); a
+ *  plain string ignores them. Without `matchMedia` (SSR, tests) none match, so the row
+ *  renders its `base`, the phone's. The same resolution as BulkActionBar's variant. */
+function useResolvedPlacement(
+  placement: FormActionsPlacement | ResponsiveFormActionsPlacement,
+): FormActionsPlacement {
+  const matches = {
+    xl: useMediaQuery(BREAKPOINTS[0][1], false),
+    lg: useMediaQuery(BREAKPOINTS[1][1], false),
+    md: useMediaQuery(BREAKPOINTS[2][1], false),
+    sm: useMediaQuery(BREAKPOINTS[3][1], false),
+  };
+  if (typeof placement === "string") return placement;
+  for (const [key] of BREAKPOINTS) {
+    const p = placement[key];
+    if (matches[key] && p !== undefined) return p;
+  }
+  return placement.base;
+}
+
+/** A CSS length: a number is pixels. */
+function cssLength(value: string | number): string {
+  return typeof value === "number" ? `${value}px` : value;
+}
+
 /**
  * What a `sticky` row sticks to — see {@link FormActionsProps.stickyWithin}.
  *  - `viewport` (default): the page's (or AppShell pane's) bottom edge, lifted onto
@@ -125,8 +176,20 @@ export interface FormActionsProps extends Omit<ComponentPropsWithoutRef<"div">,
   start?: ReactNode;
   /** Horizontal alignment. Default `end` (`between` with a `destructive` action). */
   align?: FormActionsAlign;
-  /** See {@link FormActionsPlacement}. Default `inline`. */
-  placement?: FormActionsPlacement;
+  /** See {@link FormActionsPlacement}, or one per breakpoint — see
+   *  {@link ResponsiveFormActionsPlacement}. Default `inline`. */
+  placement?: FormActionsPlacement | ResponsiveFormActionsPlacement;
+  /**
+   * While the row is `sticky`: pull it out over its container's inline padding by this
+   * much (a CSS length, a number in px) and give the same back as padding — so the
+   * rule above it and its surface run edge to edge, while the buttons stay on the
+   * content's line. Without it a sticky row in a padded card or pane is a strip inset
+   * from both sides, with the content scrolling past it in the gutters (keksdose wrote
+   * `@max-md:-mx-3 @max-md:px-3` by hand). Pass the container's padding (`"0.75rem"`,
+   * `12`, `"var(--pane-px)"`). Applied only while the resolved placement is sticky, so
+   * `placement={{ base: "sticky", md: "inline" }}` bleeds on the phone alone.
+   */
+  bleed?: string | number;
   /**
    * With `placement="sticky"`: what the row sticks to. Default `viewport`.
    *
@@ -190,8 +253,9 @@ export function FormActions({
   destructive,
   start: startSlot,
   align,
-  placement = "inline",
+  placement: placementProp = "inline",
   stickyWithin = "viewport",
+  bleed,
   form,
   children,
   className,
@@ -199,6 +263,8 @@ export function FormActions({
   ...rest
 }: FormActionsProps) {
   const labels = useKitLabels("form", DEFAULT_FORM_ACTIONS_LABELS);
+  const placement = useResolvedPlacement(placementProp);
+  const bleedLength = bleed === undefined || bleed === "" ? undefined : cssLength(bleed);
   const hasDestructive = destructive !== undefined && destructive !== null && destructive !== false;
   const hasStart = startSlot !== undefined && startSlot !== null && startSlot !== false;
   const justify = align ?? (hasDestructive || hasStart ? "between" : "end");
@@ -235,6 +301,10 @@ export function FormActions({
               // container the nav is not underneath: `--app-nav-h` is the document's,
               // and would hold the row that far above the container's own edge.
               bottom: stickyWithin === "container" ? 0 : "max(0px, calc(var(--app-nav-h, 0px) - 1px))",
+              ...(bleedLength !== undefined && {
+                marginInline: `calc(-1 * ${bleedLength})`,
+                paddingInline: bleedLength,
+              }),
               ...style,
             }
           : style

package/src/components/line-items.tsx

@@ -53,8 +53,10 @@ export interface LineItemCellContext<T> {
  *  so the list draws no header for it. */
 export type LineItemsFieldLabels = "aria" | "floating";
 
-/** The colour of a {@link LineItemsSummary}'s value. */
-export type LineItemsSummaryTone = "neutral" | "success" | "danger" | "muted";
+/** The colour of a {@link LineItemsSummary}'s value — a verdict (`success` /
+ *  `danger`), quiet (`muted`), or the money pair (`income` / `expense`, the colours
+ *  `SignedAmount` draws a figure in) for a remainder that reads as the row it settles. */
+export type LineItemsSummaryTone = "neutral" | "success" | "danger" | "muted" | "income" | "expense";
 
 /**
  * A line under the lines that says where they stand — a split's remainder ("Left to
@@ -65,13 +67,28 @@ export interface LineItemsSummary {
   label: ReactNode;
   value?: ReactNode;
   /** The value's colour. Default `neutral`. The label stays neutral: the colour is a
-   *  second signal, never the only one — the value and label carry the meaning. */
+   *  second signal, never the only one — the value and label carry the meaning.
+   *  With no `value` the line is a state on its own ("Waiting for the total"), and
+   *  the tone colours the label instead — `muted` quiets the whole line. */
   tone?: LineItemsSummaryTone;
+  /** Beside the value: a chip or badge that names the state ("Balanced" next to a
+   *  journal entry's zero difference). */
+  status?: ReactNode;
   /** A small button at the end of the line. Disabled along with the list's
-   *  `disabled`. */
-  action?: { label: ReactNode; onClick: () => void; disabled?: boolean };
+   *  `disabled`. `variant`: `secondary` (default) is a boxed button; `link` a muted
+   *  text link, for an action that is an aside rather than the way to settle it. */
+  action?: { label: ReactNode; onClick: () => void; disabled?: boolean; variant?: "secondary" | "link" };
 }
 
+/** Where a row's remove button sits. `row` (default): stacked, a row of the card to
+ *  itself (paired, the whole width); wide, its own track. `inline`: stacked, beside
+ *  the row's last field ("category + amount" over "memo + delete"); wide, unchanged. */
+export type LineItemsRemovePlacement = "row" | "inline";
+
+/** How the remove button sits in the height of a wide row: at its top, centred, or at
+ *  its foot. */
+export type LineItemsRemoveAlign = "start" | "center" | "end";
+
 export interface LineItemsColumn<T> {
   /** Stable id: the React key, and the key into `totals`. */
   key: string;
@@ -143,6 +160,14 @@ export interface LineItemsProps<T> extends Omit<ComponentPropsWithoutRef<"div">,
    *  them up (a column's `narrowSpan={2}` takes a whole row), once the pane is wide
    *  enough for two fields (18rem); narrower still, one. Default `1`. */
   narrowColumns?: 1 | 2;
+  /** Stacked, where the remove button goes: a row of its own (`row`, default) or
+   *  beside the last field (`inline`). See {@link LineItemsRemovePlacement}. */
+  removePlacement?: LineItemsRemovePlacement;
+  /** On the wide grid, the remove button's place in the row's height. Default `start`
+   *  — or `center` when a column floats its label (`fieldLabels="floating"`): a
+   *  floating field is taller than the button, and centred is level with its control.
+   *  A field that shows a message under itself grows the row; pin `start` then. */
+  removeAlign?: LineItemsRemoveAlign;
   /** Disables add and remove (the fields are the caller's to disable). */
   disabled?: boolean;
   labels?: Partial<LineItemsLabels>;
@@ -154,6 +179,14 @@ const SUMMARY_TONE: Record<LineItemsSummaryTone, string> = {
   success: "text-[var(--success)]",
   danger: "text-[var(--danger)]",
   muted: "text-[var(--text-muted)]",
+  // SignedAmount's money palette (toneTextClass "income" / "expense").
+  income: "text-[var(--money-income)]",
+  expense: "text-[var(--money-expense)]",
+};
+const REMOVE_ALIGN: Record<LineItemsRemoveAlign, string> = {
+  start: "@lg:self-start",
+  center: "@lg:self-center",
+  end: "@lg:self-end",
 };
 const FOCUSABLE =
   "input:not([disabled]):not([type=hidden]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex='-1'])";
@@ -217,6 +250,8 @@ export function LineItems<T>({
   summary,
   fieldLabels = "aria",
   narrowColumns = 1,
+  removePlacement = "row",
+  removeAlign: removeAlignProp,
   disabled = false,
   labels: labelsProp,
   className,
@@ -292,6 +327,9 @@ export function LineItems<T>({
   // its own label, a row of headers would say each name twice.
   const showHeader = columns.some((c) => !floats(c));
   const pairs = narrowColumns === 2;
+  const removeAlign = removeAlignProp ?? (columns.some(floats) ? "center" : "start");
+  const inline = removePlacement === "inline" && Boolean(onRemove) && columns.length > 0;
+  const lastColumn = columns[columns.length - 1];
 
   const headerCell = (column: LineItemsColumn<T>) => (
     <span
@@ -305,7 +343,43 @@ export function LineItems<T>({
     </span>
   );
 
+  const removeCell = (index: number, row: number, isConfirming: boolean) => (
+    <div
+      data-line-items-remove-cell=""
+      className={cn(
+        "flex justify-end @lg:justify-center",
+        REMOVE_ALIGN[removeAlign],
+        // Paired, the remove button keeps a row of its own at the card's end rather
+        // than squeezing in beside the last field — unless asked to go `inline`.
+        inline ? "shrink-0" : pairs && "@2xs:col-span-2 @lg:col-span-1",
+      )}
+    >
+      <IconButton
+        type="button"
+        data-line-items-remove=""
+        variant={isConfirming ? "danger" : "ghost"}
+        tone={isConfirming ? undefined : "danger"}
+        label={isConfirming ? labels.confirmRemove(row) : labels.remove(row)}
+        disabled={!canRemove}
+        onClick={() => void removeAt(index)}
+        onBlur={() => {
+          if (isConfirming) setConfirming(null);
+        }}
+        onKeyDown={(e) => {
+          if (e.key === "Escape" && isConfirming) {
+            e.stopPropagation();
+            setConfirming(null);
+          }
+        }}
+      >
+        <Trash2 />
+      </IconButton>
+    </div>
+  );
+
   const showTotals = totals !== undefined;
+  const summaryTone = summary?.tone ?? "neutral";
+  const summaryHasValue = hasContent(summary?.value);
   const labelColumn = showTotals ? columns.find((c) => !hasContent(totals[c.key]))?.key : undefined;
 
   return (
@@ -355,13 +429,15 @@ export function LineItems<T>({
           >
             {columns.map((column) => {
               const floating = floats(column);
-              return (
+              const isLast = inline && column === lastColumn;
+              const span = pairs && column.narrowSpan === 2 && "@2xs:col-span-2 @lg:col-span-1";
+              const cell = (
                 <div
                   key={column.key}
                   className={cn(
                     "min-w-0 space-y-1 @lg:space-y-0",
                     // The wide grid places every cell in its own track again.
-                    pairs && column.narrowSpan === 2 && "@2xs:col-span-2 @lg:col-span-1",
+                    isLast ? "flex-1" : span,
                   )}
                 >
                   {!floating && (
@@ -377,33 +453,23 @@ export function LineItems<T>({
                   })}
                 </div>
               );
-            })}
-            {onRemove && (
-              // Paired, the remove button keeps a row of its own at the card's end
-              // rather than squeezing in beside the last field.
-              <div className={cn("flex justify-end @lg:justify-center", pairs && "@2xs:col-span-2 @lg:col-span-1")}>
-                <IconButton
-                  type="button"
-                  data-line-items-remove=""
-                  variant={isConfirming ? "danger" : "ghost"}
-                  tone={isConfirming ? undefined : "danger"}
-                  label={isConfirming ? labels.confirmRemove(row) : labels.remove(row)}
-                  disabled={!canRemove}
-                  onClick={() => void removeAt(index)}
-                  onBlur={() => {
-                    if (isConfirming) setConfirming(null);
-                  }}
-                  onKeyDown={(e) => {
-                    if (e.key === "Escape" && isConfirming) {
-                      e.stopPropagation();
-                      setConfirming(null);
-                    }
-                  }}
+              if (!isLast) return cell;
+              // Inline, the last field and the remove button share one cell of the
+              // card; on the wide grid the wrapper dissolves (`contents`) and each is a
+              // track of its own again. Level with the field's control: its foot under
+              // a header copy, its middle when it floats its own label.
+              return (
+                <div
+                  key={column.key}
+                  data-line-items-inline=""
+                  className={cn("flex min-w-0 gap-2 @lg:contents", floating ? "items-center" : "items-end", span)}
                 >
-                  <Trash2 />
-                </IconButton>
-              </div>
-            )}
+                  {cell}
+                  {removeCell(index, row, isConfirming)}
+                </div>
+              );
+            })}
+            {onRemove && !inline && removeCell(index, row, isConfirming)}
           </div>
         );
       })}
@@ -454,19 +520,29 @@ export function LineItems<T>({
           data-line-items-summary=""
           className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-[var(--text-primary)]"
         >
-          <span className="min-w-0">{summary.label}</span>
-          {hasContent(summary.value) && (
-            <span
-              data-tone={summary.tone ?? "neutral"}
-              className={cn("font-semibold tabular-nums", SUMMARY_TONE[summary.tone ?? "neutral"])}
-            >
+          {/* With no value the line is a state of its own, and the label takes the
+              tone — the only place left to carry it. */}
+          <span
+            data-tone={summaryHasValue ? undefined : summaryTone}
+            className={cn("min-w-0", !summaryHasValue && SUMMARY_TONE[summaryTone])}
+          >
+            {summary.label}
+          </span>
+          {summaryHasValue && (
+            <span data-tone={summaryTone} className={cn("font-semibold tabular-nums", SUMMARY_TONE[summaryTone])}>
               {summary.value}
             </span>
           )}
+          {hasContent(summary.status) && (
+            <span data-line-items-summary-status="" className="inline-flex">
+              {summary.status}
+            </span>
+          )}
           {summary.action && (
             <Button
               type="button"
-              variant="secondary"
+              variant={summary.action.variant === "link" ? "link" : "secondary"}
+              tone={summary.action.variant === "link" ? "muted" : undefined}
               size="sm"
               className="ms-auto"
               disabled={disabled || summary.action.disabled}

package/src/components/list.tsx

@@ -160,7 +160,12 @@ interface ListItemBaseProps {
    * never operated — no buttons, links or inputs (invalid HTML in a button, and folded
    * into its name). Its text joins the row's accessible name, so give a bar that only
    * repeats a figure already in the row `aria-hidden`. Rendered in a block `<span>`,
-   * full width of the text column. Strictly a button holds phrasing content only; the
+   * full width of the TEXT COLUMN only — the column the title and subtitle are in, not
+   * the whole row: it starts after the {@link icon} / {@link leading} and stops where
+   * {@link trailing} begins, so a meter under a row with a trailing figure is as wide as
+   * the title, not run on under the figure (keksdose's budget rows). For a bar across
+   * the full row, put it in {@link children} (outside the target) or leave `trailing`
+   * off and show the figure in `meta`. Strictly a button holds phrasing content only; the
    * kit's `ProgressBar` draws `<div>`s, which every browser lays out and reads fine
    * there but an HTML validator flags.
    */
@@ -280,6 +285,13 @@ interface ListItemBaseProps {
    * the list's child and keeps both. The `<li>` becomes a column and the row takes the
    * full width, so an inline wrapper (the tooltip's `inline-flex` span) still stretches
    * the row across the list.
+   *
+   * `row` is the row BOX (a `<div>`), not the target: a wrapper that forces a prop onto
+   * its child with `cloneElement` — a save guard that injects `disabled` while a form is
+   * dirty (keksdose's SaveGuard) — sets it on that div, where it does nothing, and the
+   * button inside stays live. Pass `disabled` (or `loading`) to the ListItem yourself,
+   * from the same state the guard reads, and let the wrapper only explain it:
+   * `<ListItem disabled={dirty} renderRow={(row) => <Tooltip label="Save first">{row}</Tooltip>} />`.
    */
   renderRow?: (row: ReactElement) => ReactNode;
   /** Reaches the main target — the element with the row's name and action. */

package/src/components/progress-bar.tsx

@@ -180,6 +180,16 @@ export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">,
    * `tone="danger"` if it should read as over. Ignored for `segments` and `max={null}`.
    */
   overage?: boolean | ((over: number) => ReactNode);
+  /**
+   * Tag every figure the bar PRINTS `data-private`, so the host's demo-mode rule blurs
+   * it — the attribute `StatTile sensitive` and `Tooltip redact` carry: the `showValue`
+   * text, each `legend` row's value (yours from `legendValue` too), the unlimited
+   * figure and the `overage` line. The track, the swatches and the part names stay
+   * readable — a blurred bar is no picture at all. Before this an app with a demo-mode
+   * blur had to pass `legendValue` only to wrap the figure in a tagged span (keksdose).
+   * The `aria-valuetext` is not touched: a screen reader is not a screen-share.
+   */
+  sensitive?: boolean;
   labels?: Partial<ProgressBarLabels>;
 }
 
@@ -216,6 +226,7 @@ export function ProgressBar({
   legendValue,
   hint,
   overage,
+  sensitive = false,
   labels,
   className,
   as = "div",
@@ -233,6 +244,7 @@ export function ProgressBar({
   const text = useKitLabels("progressBar", DEFAULT_PROGRESS_BAR_LABELS, labels);
   const kitLocale = useKitLocale(locale);
   const labelId = useId();
+  const priv = sensitive ? "" : undefined;
   const hintId = useId();
   const hintNode =
     hint != null ? (
@@ -258,7 +270,7 @@ export function ProgressBar({
               {label}
             </span>
           )}
-          <span data-part="unlimited" className="ms-auto shrink-0 tabular-nums text-[var(--text-muted)]">
+          <span data-part="unlimited" data-private={priv} className="ms-auto shrink-0 tabular-nums text-[var(--text-muted)]">
             {shown !== undefined && `${shown} · `}
             {text.unlimited}
           </span>
@@ -320,7 +332,7 @@ export function ProgressBar({
     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)]">
+      <p id={`${hintId}-over`} data-part="overage" data-private={priv} className="mt-1 text-xs text-[var(--danger)]">
         {typeof overage === "function"
           ? overage(over)
           : text.overLimit(new Intl.NumberFormat(kitLocale).format(over))}
@@ -344,7 +356,7 @@ export function ProgressBar({
           {showValue && valueText !== undefined && (
             // Hidden: the same words are the bar's aria-valuetext, and reading them
             // twice in a row is noise.
-            <span aria-hidden className="ms-auto shrink-0 tabular-nums text-[var(--text-muted)]">
+            <span aria-hidden data-part="value" data-private={priv} className="ms-auto shrink-0 tabular-nums text-[var(--text-muted)]">
               {valueText}
             </span>
           )}
@@ -426,7 +438,11 @@ export function ProgressBar({
               {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)]">
+              <span
+                data-part="legend-value"
+                data-private={priv}
+                className="ms-auto shrink-0 text-xs tabular-nums text-[var(--text-muted)]"
+              >
                 {legendValue ? legendValue(seg, formatPart(seg.value), i) : formatPart(seg.value)}
               </span>
             </li>

package/src/components/signed-amount.tsx

@@ -106,8 +106,17 @@ export const DEFAULT_SIGNED_AMOUNT_LABELS: SignedAmountLabels = {
 interface SignedFormatProps {
   /** ISO 4217 code: format as money. */
   currency?: string;
-  /** `"percent"` reads `value` as a RATIO (`0.12` → 12 %), as `StatTile`'s delta does. */
+  /** `"percent"` reads `value` as a RATIO (`0.12` → 12 %), as `StatTile`'s delta does
+   *  — or as percent POINTS with `ratio={false}`. */
   unit?: "value" | "percent";
+  /** With `unit="percent"`: `true` (default) — `value` is a ratio, `0.12` is 12 %.
+   *  `false` — `value` is already in percent POINTS, `12` is 12 %, as `formatPercent`'s
+   *  `ratio` option reads it. Backends send points (keksdose's price changes, kastlan's
+   *  `change_pct`), and without this every site divided by 100 — and wrote its
+   *  `flatWithin` as a ratio (`0.005`) beside a value it had to convert. With
+   *  `ratio={false}` the value AND `flatWithin` are in points (`flatWithin={0.5}` is
+   *  half a point). Ignored for any other unit. */
+  ratio?: boolean;
   /** Compact notation: 12 400 → "12K". */
   compact?: boolean;
   /** Fraction digits, as `formatNumber`'s `digits`. */
@@ -118,11 +127,11 @@ interface SignedFormatProps {
   locale?: string;
 }
 
-function useMagnitudeFormatter({ currency, unit, compact, digits, format, locale }: SignedFormatProps) {
+function useMagnitudeFormatter({ currency, unit, ratio, 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 (unit === "percent") return formatPercent(magnitude, { locale: kitLocale, compact, digits, ratio });
     if (currency) return formatMoney(magnitude, currency, { locale: kitLocale, compact, digits });
     return formatNumber(magnitude, { locale: kitLocale, compact, digits });
   };
@@ -200,6 +209,7 @@ export function SignedAmount({
   value,
   currency,
   unit,
+  ratio,
   compact,
   digits,
   format,
@@ -216,7 +226,7 @@ export function SignedAmount({
   ...rest
 }: SignedAmountProps) {
   const text = useKitLabels("signedAmount", DEFAULT_SIGNED_AMOUNT_LABELS, labels);
-  const fmt = useMagnitudeFormatter({ currency, unit, compact, digits, format, locale });
+  const fmt = useMagnitudeFormatter({ currency, unit, ratio, compact, digits, format, locale });
   const finite = Number.isFinite(value);
   const dir = finite ? directionOf(value, flatWithin) : "flat";
   const amount = finite ? fmt(Math.abs(value)) : "—";
@@ -281,6 +291,7 @@ export function Delta({
   value,
   currency,
   unit,
+  ratio,
   compact,
   digits,
   format,
@@ -296,7 +307,7 @@ export function Delta({
   ...rest
 }: DeltaProps) {
   const text = useKitLabels("statTile", DEFAULT_STAT_TILE_LABELS, labels);
-  const fmt = useMagnitudeFormatter({ currency, unit, compact, digits, format, locale });
+  const fmt = useMagnitudeFormatter({ currency, unit, ratio, compact, digits, format, locale });
   if (!Number.isFinite(value)) return null;
   const amount = fmt(Math.abs(value));
   const dir = directionOf(value, flatWithin);