@eifi1/ui-kit 0.48.2 → 0.50.0

package/src/lib/format.ts

@@ -1,8 +1,13 @@
 import { useMemo } from "react";
 import { useKitLocale, useKitTimeZone } from "../i18n/kit-labels";
 import { parseIsoDate } from "./dates";
+import { formatWithMinus, type MinusStyle } from "./minus";
 import { roundHalfAway } from "./round";
 
+export type { MinusStyle } from "./minus";
+// 0.50 (KIT-1 follow-up): the kit's minus for an app's OWN `Intl.NumberFormat` wrapper.
+export { formatWithMinus } from "./minus";
+
 /**
  * Number, money, percentage, date and relative-time formatting — `Intl`, in one place,
  * for the figures an app prints OUTSIDE a kit component.
@@ -19,9 +24,18 @@ import { roundHalfAway } from "./round";
  * functions bound to the `<UiKitProvider locale>`, so a page formats exactly like the
  * kit components on it.
  *
- * A missing value — `null`, `undefined`, `NaN`, an unparseable date — formats as
- * `empty` (default "—", the dash `StatTile` shows for no value), never as "NaN" or
- * "Invalid Date".
+ * A missing value — `null`, `undefined`, an unparseable date — formats as `empty`
+ * (default "—", the dash `StatTile` shows for no value), never as "NaN" or "Invalid
+ * Date". A number may also arrive as a numeric STRING (0.49, KIT-2) — "1850.00", "-12.5",
+ * "0": a Decimal field off a Python API — and is formatted like the number. Anything
+ * else (a non-numeric string, an object, `NaN`, ±`Infinity`) prints `empty` too, but is
+ * a bug upstream rather than a gap in the data, so a development build says so on the
+ * console, once per call site. Zero is a figure: `0` and `"0"` print "CHF 0.00", never
+ * the dash.
+ *
+ * A negative figure carries the typographic minus, U+2212 (0.49, KIT-1), in every
+ * locale — `Intl` writes a hyphen in most. `minus: "ascii"` for text a machine reads
+ * back (a CSV, the clipboard).
  */
 
 /** What every formatter here prints for a missing value, unless told otherwise. */
@@ -47,6 +61,14 @@ export interface FormatNumberBaseOptions extends BaseOptions {
   signDisplay?: Intl.NumberFormatOptions["signDisplay"];
   /** Any further `Intl.NumberFormat` options, merged over the ones above. */
   options?: Intl.NumberFormatOptions;
+  /**
+   * The minus sign of a negative figure (0.49, KIT-1). `"typographic"` (default):
+   * U+2212, as wide as "+" and the digits, as `SignedAmount` prints it — in every
+   * locale, also where `Intl` writes a hyphen. `"ascii"`: U+002D, for an export a
+   * machine parses back (a CSV download, the clipboard) — there, also pass
+   * `options: { useGrouping: false }` or write the raw number.
+   */
+  minus?: MinusStyle;
 }
 
 /** The options {@link formatNumber} takes: the shared ones plus a free-text `unit`. */
@@ -115,44 +137,113 @@ function numberOptions(o: FormatNumberBaseOptions): Intl.NumberFormatOptions {
   };
 }
 
-function isMissing(value: number | null | undefined): value is null | undefined {
-  // ±Infinity too (lenkbank, adopting 0.13): a division by zero upstream is a missing
-  // figure, and "∞" printed in a money or measurement column reads like data.
-  return value === null || value === undefined || !Number.isFinite(value);
+/**
+ * What the number formatters take (0.49, KIT-2): a number, a numeric string ("1850.00",
+ * "-12.5", "1e3" — what a Decimal arrives as in JSON), or `null` / `undefined` for no
+ * value. A string is read with `Number()`, so a figure with more significant digits than
+ * a double holds (about 15–17) is printed as its nearest double.
+ */
+export type FormattableNumber = number | string | null | undefined;
+
+/** A plain decimal: optional sign, digits with an optional point, an optional exponent.
+ *  No grouping marks, no decimal comma, no currency — those are formatted text, and
+ *  reading them back is a locale's guess. */
+const NUMERIC_STRING = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+/** The kit's dev switch, as `lib/logger.ts` reads it: a development build, never a
+ *  production one (the consumer's bundler makes `import.meta.env.DEV` false) and never
+ *  under vitest. Read per call so a test can switch it on with `vi.stubEnv`. */
+function devWarnings(): boolean {
+  return Boolean(import.meta.env?.DEV) && !import.meta.env?.VITEST;
+}
+
+const warnedSites = new Set<string>();
+/** This module's own frames, skipped to find the caller ("Object.formatMoney" is a
+ *  `useKitFormat` wrapper). */
+const OWN_FRAME = /\b(?:formatNumber|formatMoney|formatPercent|toFormattable|warnInvalid|callSite)\b/;
+
+/** The first stack frame outside the formatters: where the bad value was passed. */
+function callSite(): string {
+  const frames = (new Error().stack ?? "").split("\n").slice(1);
+  return frames.find((frame) => !OWN_FRAME.test(frame))?.trim() ?? "";
+}
+
+function describeValue(value: unknown): string {
+  if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") return String(value);
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return Object.prototype.toString.call(value);
+  }
+}
+
+/** A development build's console note about an invalid value — once per call site. */
+function warnInvalid(fn: string, value: unknown): void {
+  if (!devWarnings()) return;
+  const site = callSite();
+  const key = `${fn}|${site || typeof value}`;
+  if (warnedSites.has(key)) return;
+  warnedSites.add(key);
+  const type = Array.isArray(value) ? "array" : typeof value;
+  console.warn(
+    `[ui-kit] ${fn} got ${describeValue(value)} (${type}), which is not a number: printed the empty value. ` +
+      "Pass a number, a numeric string, or null/undefined for a missing value." +
+      (site ? `\n  at ${site.replace(/^at /, "")}` : ""),
+  );
+}
+
+/**
+ * `value` as a finite number to format, or `undefined` to print `empty`. `null` and
+ * `undefined` are a missing value and pass quietly; anything that is neither a finite
+ * number nor a numeric string is an invalid one — ±Infinity included (lenkbank, adopting
+ * 0.13: a division by zero upstream; "∞" in a money column reads like data) — and a
+ * development build warns. `-0` is folded into `0`: zero carries no sign.
+ */
+function toFormattable(fn: string, value: unknown): number | undefined {
+  if (value === null || value === undefined) return undefined;
+  let n: number | undefined;
+  if (typeof value === "number") n = value;
+  else if (typeof value === "string" && NUMERIC_STRING.test(value.trim())) n = Number(value.trim());
+  if (n === undefined || !Number.isFinite(n)) {
+    warnInvalid(fn, value);
+    return undefined;
+  }
+  return n + 0;
 }
 
 /** A number in `locale`: "1,234.5", "1.234,5", "1’234.5" — with `unit`, "3.400 N". */
-export function formatNumber(value: number | null | undefined, options: FormatNumberOptions = {}): string {
-  if (isMissing(value)) return options.empty ?? EMPTY_FORMATTED_VALUE;
-  const figure = numberFormatter(options.locale, numberOptions(options)).format(value);
+export function formatNumber(value: FormattableNumber, options: FormatNumberOptions = {}): string {
+  const n = toFormattable("formatNumber", value);
+  if (n === undefined) return options.empty ?? EMPTY_FORMATTED_VALUE;
+  const figure = formatWithMinus(numberFormatter(options.locale, numberOptions(options)), n, options.minus);
   return options.unit ? `${figure}${UNIT_SEPARATOR}${options.unit}` : figure;
 }
 
 /** An amount of `currency` (ISO 4217) in `locale`: "CHF 1’234.50", "1.234,50 €". */
-export function formatMoney(
-  value: number | null | undefined,
-  currency: string,
-  options: FormatMoneyOptions = {},
-): string {
-  if (isMissing(value)) return options.empty ?? EMPTY_FORMATTED_VALUE;
-  return numberFormatter(options.locale, {
+export function formatMoney(value: FormattableNumber, currency: string, options: FormatMoneyOptions = {}): string {
+  const n = toFormattable("formatMoney", value);
+  if (n === undefined) return options.empty ?? EMPTY_FORMATTED_VALUE;
+  const formatter = numberFormatter(options.locale, {
     style: "currency",
     currency,
     ...(options.currencyDisplay ? { currencyDisplay: options.currencyDisplay } : null),
     ...numberOptions(options),
-  }).format(value);
+  });
+  return formatWithMinus(formatter, n, options.minus);
 }
 
 /** A percentage in `locale` ("12%", "12 %", "+1.25%"). See {@link FormatPercentOptions.ratio}
  *  for what `value` means. Default digits: at most one. */
-export function formatPercent(value: number | null | undefined, options: FormatPercentOptions = {}): string {
-  if (isMissing(value)) return options.empty ?? EMPTY_FORMATTED_VALUE;
-  const ratio = options.ratio === false ? value / 100 : value;
-  return numberFormatter(options.locale, {
+export function formatPercent(value: FormattableNumber, options: FormatPercentOptions = {}): string {
+  const n = toFormattable("formatPercent", value);
+  if (n === undefined) return options.empty ?? EMPTY_FORMATTED_VALUE;
+  const ratio = options.ratio === false ? n / 100 : n;
+  const formatter = numberFormatter(options.locale, {
     style: "percent",
     ...(options.digits === undefined ? { maximumFractionDigits: 1 } : null),
     ...numberOptions(options),
-  }).format(ratio);
+  });
+  return formatWithMinus(formatter, ratio, options.minus);
 }
 
 /* ── Dates ─────────────────────────────────────────────────────────────────── */
@@ -327,13 +418,9 @@ type WithoutLocale<T> = Omit<T, "locale"> & { locale?: string };
 export interface KitFormat {
   /** The locale they format in — the provider's, or `undefined` (runtime default). */
   locale: string | undefined;
-  formatNumber: (value: number | null | undefined, options?: WithoutLocale<FormatNumberOptions>) => string;
-  formatMoney: (
-    value: number | null | undefined,
-    currency: string,
-    options?: WithoutLocale<FormatMoneyOptions>,
-  ) => string;
-  formatPercent: (value: number | null | undefined, options?: WithoutLocale<FormatPercentOptions>) => string;
+  formatNumber: (value: FormattableNumber, options?: WithoutLocale<FormatNumberOptions>) => string;
+  formatMoney: (value: FormattableNumber, currency: string, options?: WithoutLocale<FormatMoneyOptions>) => string;
+  formatPercent: (value: FormattableNumber, options?: WithoutLocale<FormatPercentOptions>) => string;
   formatDate: (
     value: DateInput,
     style?: FormatDateStyle | Intl.DateTimeFormatOptions,

package/src/lib/minus.ts

@@ -0,0 +1,50 @@
+/**
+ * The one minus sign (0.49, KIT-1). `Intl.NumberFormat` writes a negative with the
+ * HYPHEN-MINUS (U+002D) in nearly every locale — en, de-CH, fr, it, es, hu, zh — and
+ * with the typographic MINUS SIGN (U+2212) in a few (sv, fi). The kit prints U+2212
+ * everywhere, as `SignedAmount` always has: it is as wide as "+" and the tabular
+ * digits, so a column of signed figures lines up, and it does not break a line the way
+ * a hyphen may.
+ *
+ * `"ascii"` is the other way round, for text a machine reads back — a CSV, the
+ * clipboard: every minus becomes U+002D, whatever the locale wrote, so `Number()` and a
+ * spreadsheet parse it.
+ */
+export type MinusStyle = "typographic" | "ascii";
+
+/** U+2212 MINUS SIGN. */
+export const TYPOGRAPHIC_MINUS = "\u2212";
+
+/** The parts `formatToParts` writes a minus in (the exponent's, under `notation:
+ *  "scientific"`, too). */
+const MINUS_PARTS: ReadonlySet<string> = new Set(["minusSign", "exponentMinusSign"]);
+
+/**
+ * `formatter.format(value)` with every minus sign in `minus` style. Only the parts
+ * `Intl` marks as a minus are touched — a hyphen inside a currency's name
+ * ("Bosnia-Herzegovina convertible marks") stays — and only when the text holds the
+ * other sign at all, so a positive figure costs no `formatToParts`.
+ *
+ * Public since 0.50 (the KIT-1 follow-up): an app that keeps its OWN `Intl.NumberFormat`
+ * wrapper (a currency with app-specific digits, a quantity) calls it in place of
+ * `formatter.format(value)`, so its negatives match the kit's "−". Where the wrapper only
+ * re-states `formatMoney` / `formatNumber`, route it through those instead.
+ *
+ * @example
+ *   const eur = new Intl.NumberFormat("en", { style: "currency", currency: "EUR" });
+ *   formatWithMinus(eur, -150);          // "−€150.00"
+ *   formatWithMinus(eur, -150, "ascii"); // "-€150.00", for a CSV
+ */
+export function formatWithMinus(
+  formatter: Intl.NumberFormat,
+  value: number,
+  minus: MinusStyle = "typographic",
+): string {
+  const text = formatter.format(value);
+  const [wanted, other] = minus === "ascii" ? ["-", TYPOGRAPHIC_MINUS] : [TYPOGRAPHIC_MINUS, "-"];
+  if (!text.includes(other)) return text;
+  return formatter
+    .formatToParts(value)
+    .map((part) => (MINUS_PARTS.has(part.type) ? wanted : part.value))
+    .join("");
+}

package/src/lib/status-tone.ts

@@ -0,0 +1,43 @@
+/**
+ * What a status means, in five domain-free words, and the tone that says it (0.49 KIT-8).
+ *
+ * Every app paints its statuses by hand: kastlan's ~15 enums each carry a Chip tone
+ * (`shared/enums/enum-meta.ts`), keksdose's job and transaction states theirs, and the
+ * same meaning drifted into different colours — "unpaid" amber in one table, brand in
+ * the next. The kind is the decision ("does the reader have to act?"), the tone only
+ * its colour, so an app maps each of its states to a kind once and the colours agree
+ * everywhere:
+ *
+ * | kind | tone | for |
+ * |---|---|---|
+ * | `good` | `success` | done, settled, healthy: nothing to do (Paid, Verified) |
+ * | `attention` | `warning` | needs a look or an action soon, nothing broken yet (Unpaid, Due soon) |
+ * | `problem` | `danger` | something is wrong or late and needs action now (Overdue, Failed) |
+ * | `active` | `info` | in progress or current, neither good nor bad (Running, Sent) |
+ * | `inactive` | `neutral` | over, paused or not started: out of the way (Draft, Archived) |
+ *
+ * `brand` is not a status tone: it is the app's own colour, and a status in it reads as
+ * "this is the app" rather than as a state. Money (`income` / `expense`) is not one
+ * either: it says which way an amount flows, not how a record stands.
+ */
+export type StatusKind = "good" | "attention" | "problem" | "active" | "inactive";
+
+/** The tones a {@link StatusKind} maps to — a subset of `ChipTone` and `StatusDotTone`. */
+export type StatusTone = "success" | "warning" | "danger" | "info" | "neutral";
+
+/** The five kinds, in the order the table above lists them. */
+export const STATUS_KINDS: readonly StatusKind[] = ["good", "attention", "problem", "active", "inactive"];
+
+const TONES: Readonly<Record<StatusKind, StatusTone>> = {
+  good: "success",
+  attention: "warning",
+  problem: "danger",
+  active: "info",
+  inactive: "neutral",
+};
+
+/** The tone for a status kind: good → success, attention → warning, problem → danger,
+ *  active → info, inactive → neutral. See {@link StatusKind}. */
+export function statusTone(kind: StatusKind): StatusTone {
+  return TONES[kind];
+}

package/src/settings/settings-layout.tsx

@@ -323,6 +323,7 @@ export function SettingsLayout<G extends string>({
       <div className={pageClass} data-settings-view="group">
         <PageHeader
           size="compact"
+          documentTitle={false}
           title={open.title}
           description={open.help}
           breadcrumbs={
@@ -347,7 +348,7 @@ export function SettingsLayout<G extends string>({
       </div>
     ) : (
       <div className={pageClass} data-settings-view="list">
-        <PageHeader size="compact" title={pageTitle} />
+        <PageHeader size="compact" documentTitle={false} title={pageTitle} />
         {searchField}
         {searching ? (
           results
@@ -409,7 +410,7 @@ export function SettingsLayout<G extends string>({
       );
     body = (
       <div className={pageClass} data-settings-view="desktop">
-        <PageHeader size="compact" title={pageTitle} />
+        <PageHeader size="compact" documentTitle={false} title={pageTitle} />
         {searchField}
         <div className="md:grid md:grid-cols-[14rem_minmax(0,1fr)] md:gap-6">
           {withSidebarFooter(

package/src/shell/account-menu-language.tsx

@@ -4,6 +4,7 @@ import { Globe } from "lucide-react";
 import { Disclosure } from "../components/disclosure";
 import { MenuItem } from "../components/menu-item";
 import { DEFAULT_TOP_BAR_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { languageCodeLabel } from "./language-code";
 
 /** One offered language in the account menu's sub-list. */
 export interface AccountMenuLanguageOption {
@@ -56,7 +57,7 @@ export interface AccountMenuLanguageProps {
 /**
  * The language choice INSIDE the account menu (docs/top-bar-harmonization.md §2.3),
  * keksdose's sub-list: a `Disclosure variant="menu"` row — the globe, "Language", the
- * active language's flag and the chevron — that opens in place onto one checked
+ * active language's flag and code ("DE") and the chevron — that opens in place onto one checked
  * `MenuItem` per language. Inline rather than a nested popover: a popover inside a
  * popover fights the outside click and has nowhere to go on a phone (keksdose #140).
  *
@@ -87,7 +88,18 @@ export function AccountMenuLanguage({
               <Globe aria-hidden className="size-4" />
               {label ?? words.language}
             </span>
-            {active && flagOf(active)}
+            {active && (
+              // The flag alone could not tell de-CH, fr-CH and it-CH apart (one Swiss
+              // flag each), so the code sits beside it (0.49 KIT-10); the row's name
+              // carries the language's own name.
+              <span className="flex items-center gap-1.5">
+                {flagOf(active)}
+                <span aria-hidden className="text-xs font-semibold tabular-nums tracking-wide text-secondary">
+                  {languageCodeLabel(active.code)}
+                </span>
+                <span className="sr-only">{active.label}</span>
+              </span>
+            )}
           </span>
         }
       >

package/src/shell/app-shell-labels.ts

@@ -7,4 +7,5 @@ import type { AppShellMoreLabels } from "./app-shell";
 export const DEFAULT_APP_SHELL_MORE_LABELS: AppShellMoreLabels = {
   more: "More",
   moreTitle: "More pages",
+  overview: "Overview",
 };