@eifi1/ui-kit 0.10.0 → 0.12.0

package/src/components/signed-amount.tsx

@@ -0,0 +1,286 @@
+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). */
+  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 />}
+        {/* Flat with an arrow is the dash alone, as on a tile; without one, the zero. */}
+        <span aria-hidden>{dir === "flat" && arrow ? null : amount}</span>
+        <span className="sr-only">{spoken}</span>
+      </span>
+      {label != null && <span className="text-[var(--text-muted)]">{label}</span>}
+    </span>
+  );
+}

package/src/components/skeleton.tsx

@@ -21,6 +21,13 @@ export interface SkeletonProps extends Omit<ComponentPropsWithoutRef<"div">, "ch
   shape?: SkeletonShape;
   /** For `line`: this many lines, the last one shorter — a paragraph's outline. */
   lines?: number;
+  /**
+   * Say what is loading, once: wraps the placeholder in a `role="status"` region with
+   * this as its (visually hidden) text — kastlan's activity feed (activity-feed:52)
+   * built exactly that by hand around `<Skeleton lines={5} />`. The placeholder itself
+   * stays hidden. Left out, nothing is announced, as before.
+   */
+  label?: string;
 }
 
 const SHAPE: Record<SkeletonShape, string> = {
@@ -37,10 +44,21 @@ const SHAPE: Record<SkeletonShape, string> = {
  *
  * ALWAYS `aria-hidden`. A placeholder is not content, and a reader that met twelve
  * unnamed grey boxes would have learned nothing. Say "loading" once, where it
- * belongs: `aria-busy` on the region being filled, or a `Spinner` / sr-only line
- * beside the skeletons.
+ * belongs: `aria-busy` on the region being filled, a `Spinner` / sr-only line
+ * beside the skeletons, or this component's own `label`.
  */
-export function Skeleton({ shape = "line", lines, className, ...rest }: SkeletonProps) {
+export function Skeleton({ label, ...props }: SkeletonProps) {
+  if (!label) return <SkeletonFill {...props} />;
+  return (
+    // `relative`: the containing block for the sr-only text (sr-only-containment.test).
+    <div role="status" className="relative" data-skeleton-status="">
+      <span className="sr-only">{label}</span>
+      <SkeletonFill {...props} />
+    </div>
+  );
+}
+
+function SkeletonFill({ shape = "line", lines, className, ...rest }: Omit<SkeletonProps, "label">) {
   if (shape === "line" && lines !== undefined && lines > 1) {
     return (
       <div {...rest} aria-hidden className={cn("flex flex-col gap-2", className)} data-skeleton="lines">

package/src/components/stat-tile.tsx

@@ -2,7 +2,8 @@ import { isValidElement, 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";
-import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { useKitLabels, useKitLink, useKitLocale } from "../i18n/kit-labels";
+import { pickLinkRenderer, RenderedKitLink } from "./text-link";
 import { Card, FieldHint } from "./ui";
 import { Sparkline } from "./sparkline";
 import { Tooltip } from "./tooltip";
@@ -219,7 +220,8 @@ export interface StatTileProps
   /** 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
-   *  `<a>` reloads a single-page app. Default: `<a>`. */
+   *  `<a>` reloads a single-page app. Default: the `<UiKitProvider linkComponent>`
+   *  (for an in-app `href`), then `<a>`. */
   renderLink?: (props: StatTileLinkProps) => ReactElement;
   /** Makes the tile a button (ignored when `href` is given). */
   onClick?: () => void;
@@ -297,6 +299,7 @@ export function StatTile({
   ...rest
 }: StatTileProps) {
   const text = useKitLabels("statTile", DEFAULT_STAT_TILE_LABELS, labels);
+  const kitLink = useKitLink();
   const [labelEl, setLabelEl] = useState<HTMLElement | null>(null);
   const labelCut = useIsTruncated(truncateLabel ? labelEl : null);
   const kitLocale = useKitLocale(locale);
@@ -334,8 +337,11 @@ export function StatTile({
       "aria-describedby": describedBy,
       children: label,
     };
+    const kit = pickLinkRenderer<StatTileLinkProps>(undefined, kitLink, href);
     labelNode = renderLink ? (
       renderLink(linkProps)
+    ) : kit ? (
+      <RenderedKitLink render={kit} props={linkProps} />
     ) : (
       <a href={href} className={stretched} aria-describedby={describedBy}>
         {label}

package/src/components/status-dot.tsx

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