@cosmicdrift/kumiko-headless 0.211.0 → 0.213.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.211.0",
+  "version": "0.213.0",
   "description": "Headless UI logic for Kumiko — Dispatcher contract, Form-Controller, View-Model, Nav-Resolver. Plattform- und React-frei; jeder Renderer (renderer, renderer-web, renderer-native, …) komponiert darauf.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,7 +36,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.211.0",
+    "@cosmicdrift/kumiko-framework": "0.213.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

package/src/format/__tests__/format.test.ts

@@ -90,3 +90,67 @@ describe("applyFormatSpec — timestamp/date (formatDateCell-Pfad)", () => {
     expect(out).toContain("2026");
   });
 });
+
+describe("applyFormatSpec — unit (fw#2187)", () => {
+  test("km/m/kg/percent gehen über Intl.NumberFormat(style:'unit'), locale-korrekt", () => {
+    expect(applyFormatSpec({ format: "unit", unit: "km" }, 58)).toBe(
+      new Intl.NumberFormat(undefined, {
+        style: "unit",
+        unit: "kilometer",
+        unitDisplay: "short",
+      }).format(58),
+    );
+    expect(applyFormatSpec({ format: "unit", unit: "km", locale: "de-DE" }, 58)).toBe("58 km");
+    expect(applyFormatSpec({ format: "unit", unit: "kg", locale: "de-DE" }, 2.5)).toBe("2,5 kg");
+    // de-DE percent uses a narrow no-break space (U+202F) before "%", not a
+    // plain space — assert against Intl's own output rather than guessing.
+    expect(applyFormatSpec({ format: "unit", unit: "percent", locale: "de-DE" }, 12)).toBe(
+      new Intl.NumberFormat("de-DE", {
+        style: "unit",
+        unit: "percent",
+        unitDisplay: "short",
+      }).format(12),
+    );
+  });
+
+  test("m2 hat kein ECMA-402-sanktioniertes Intl-Unit (RangeError für 'square-meter') — Zahl + literales Suffix", () => {
+    expect(applyFormatSpec({ format: "unit", unit: "m2", locale: "de-DE" }, 58)).toBe("58 m²");
+    expect(applyFormatSpec({ format: "unit", unit: "m2", locale: "de-DE" }, 1234.5)).toBe(
+      "1.234,5 m²",
+    );
+  });
+
+  test("unitDisplay steuert long", () => {
+    expect(
+      applyFormatSpec({ format: "unit", unit: "km", locale: "en-US", unitDisplay: "long" }, 3),
+    ).toBe("3 kilometers");
+    expect(
+      applyFormatSpec({ format: "unit", unit: "km", locale: "en-US", unitDisplay: "narrow" }, 3),
+    ).toBe(
+      new Intl.NumberFormat("en-US", {
+        style: "unit",
+        unit: "kilometer",
+        unitDisplay: "narrow",
+      }).format(3),
+    );
+  });
+
+  test("nicht-numerischer Wert fällt auf String zurück", () => {
+    expect(applyFormatSpec({ format: "unit", unit: "km" }, "not-a-number")).toBe("not-a-number");
+  });
+
+  test("fehlende/unbekannte unit fällt auf String zurück, statt zu werfen", () => {
+    expect(applyFormatSpec({ format: "unit" }, 58)).toBe("58");
+    expect(applyFormatSpec({ format: "unit", unit: "does-not-exist" }, 58)).toBe("58");
+  });
+
+  test("Prototype-Chain-Keys (toString, constructor) zählen NICHT als unit — Object.hasOwn statt `in`", () => {
+    expect(applyFormatSpec({ format: "unit", unit: "toString" }, 58)).toBe("58");
+    expect(applyFormatSpec({ format: "unit", unit: "constructor" }, 58)).toBe("58");
+  });
+
+  test("leerer Wert collapst zu '' wie jedes andere Nicht-priority-Format", () => {
+    expect(applyFormatSpec({ format: "unit", unit: "km" }, null)).toBe("");
+    expect(applyFormatSpec({ format: "unit", unit: "km" }, "")).toBe("");
+  });
+});

package/src/format/index.ts

@@ -80,6 +80,54 @@ function formatNumberCell(value: unknown, locale?: string): string {
   }
 }
 
+// Two-tier unit table for `{ format: "unit" }`. Keys mirror
+// @cosmicdrift/kumiko-types' UnitKey (kept as a local literal union instead
+// of an import — headless has no build-time dependency on kumiko-types
+// today, and applyFormatSpec's spec param is already an untyped
+// Record<string, unknown>, cast per-case like every other format below).
+const UNIT_INTL_IDS = {
+  km: "kilometer",
+  m: "meter",
+  kg: "kilogram",
+  percent: "percent",
+} as const;
+
+// "m2" (square meter) has no ECMA-402 sanctioned unit — Intl.NumberFormat
+// throws RangeError for "square-meter". Locale-format the number and append
+// the literal suffix instead of going through `style: "unit"`.
+const UNIT_SUFFIXES = { m2: "m²" } as const;
+
+type UnitKey = keyof typeof UNIT_INTL_IDS | keyof typeof UNIT_SUFFIXES;
+
+function isUnitKey(unit: string): unit is UnitKey {
+  // Object.hasOwn, not `in` — `in` walks the prototype chain, so
+  // "toString" or "constructor" would pass as a valid unit key.
+  return Object.hasOwn(UNIT_INTL_IDS, unit) || Object.hasOwn(UNIT_SUFFIXES, unit);
+}
+
+function formatUnitCell(
+  value: unknown,
+  unit: string | undefined,
+  locale: string | undefined,
+  unitDisplay: Intl.NumberFormatOptions["unitDisplay"],
+): string {
+  const n = typeof value === "number" ? value : Number(value);
+  if (unit === undefined || !isUnitKey(unit) || !Number.isFinite(n)) return String(value);
+  if (Object.hasOwn(UNIT_INTL_IDS, unit)) {
+    try {
+      return new Intl.NumberFormat(locale, {
+        style: "unit",
+        unit: UNIT_INTL_IDS[unit as keyof typeof UNIT_INTL_IDS],
+        unitDisplay,
+      }).format(n);
+    } catch {
+      // Malformed BCP-47 locale tag — mirrors formatNumberCell's fallback below.
+      return formatNumberCell(n, locale);
+    }
+  }
+  return `${formatNumberCell(n, locale)} ${UNIT_SUFFIXES[unit as keyof typeof UNIT_SUFFIXES]}`;
+}
+
 export { escapeHtml, escapeHtmlAttr, escapeXml, isSafeHref, stripControlChars } from "./escape";
 export { type HtmlValue, html, RawHtml, raw } from "./html-template";
 export { currencyDecimals } from "./money";
@@ -115,6 +163,13 @@ export function applyFormatSpec(
     case "decimal":
     case "bigInt":
       return formatNumberCell(value, spec["locale"] as string | undefined);
+    case "unit":
+      return formatUnitCell(
+        value,
+        spec["unit"] as string | undefined,
+        spec["locale"] as string | undefined,
+        (spec["unitDisplay"] as Intl.NumberFormatOptions["unitDisplay"]) ?? "short",
+      );
     case "priority": {
       const emptyLabel = (spec["emptyLabel"] as string | undefined) ?? "—";
       const prefix = (spec["prefix"] as string | undefined) ?? "";