@cosmicdrift/kumiko-headless 0.37.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.37.0",
+  "version": "0.39.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>",
@@ -28,7 +28,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.35.0",
+    "@cosmicdrift/kumiko-framework": "0.38.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

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

@@ -35,8 +35,8 @@ describe("escapeHtmlAttr", () => {
     expect(escapeHtmlAttr(`& " < >`)).toBe("&amp; &quot; &lt; &gt;");
   });
 
-  test("does not escape '", () => {
-    expect(escapeHtmlAttr("it's")).toBe("it's");
+  test("escapes ' so single-quoted attributes cannot break out", () => {
+    expect(escapeHtmlAttr("it's")).toBe("it&#39;s");
   });
 
   test("plain attribute value passes through", () => {

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

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import { applyFormatSpec } from "../index";
+
+describe("applyFormatSpec — priority", () => {
+  test("rendert emptyLabel für undefined/null/leer/0 (nicht den globalen ''-Collapse)", () => {
+    expect(applyFormatSpec({ format: "priority" }, undefined)).toBe("—");
+    expect(applyFormatSpec({ format: "priority" }, null)).toBe("—");
+    expect(applyFormatSpec({ format: "priority" }, "")).toBe("—");
+    expect(applyFormatSpec({ format: "priority" }, 0)).toBe("—");
+  });
+
+  test("custom emptyLabel + prefix", () => {
+    expect(applyFormatSpec({ format: "priority", emptyLabel: "none" }, null)).toBe("none");
+    expect(applyFormatSpec({ format: "priority", prefix: "P" }, 2)).toBe("P2");
+  });
+});
+
+describe("applyFormatSpec — leere Werte anderer Formate", () => {
+  test("collapsen zu ''", () => {
+    expect(applyFormatSpec({ format: "boolean" }, undefined)).toBe("");
+    expect(applyFormatSpec({ format: "currency", symbol: "€" }, null)).toBe("");
+    expect(applyFormatSpec({ format: "timestamp" }, "")).toBe("");
+  });
+});
+
+describe("applyFormatSpec — boolean/currency", () => {
+  test("boolean mit Default- und Custom-Labels", () => {
+    expect(applyFormatSpec({ format: "boolean" }, true)).toBe("✓");
+    expect(applyFormatSpec({ format: "boolean" }, false)).toBe("");
+    expect(applyFormatSpec({ format: "boolean", trueLabel: "ja", falseLabel: "nein" }, false)).toBe(
+      "nein",
+    );
+  });
+
+  test("currency hängt Symbol an", () => {
+    expect(applyFormatSpec({ format: "currency", symbol: "€" }, 12)).toBe("12 €");
+    expect(applyFormatSpec({ format: "currency" }, 12)).toBe("12");
+  });
+});
+
+describe("applyFormatSpec — timestamp/date (formatDateCell-Pfad)", () => {
+  // Mittag UTC: das Datum kippt in keiner Zeitzone UTC-11..UTC+11 —
+  // deterministisch auf CI (UTC) und lokal (CET).
+  const instant = "2026-01-15T12:00:00Z";
+
+  test("timestamp mit locale+dateStyle+timeStyle rendert lokalisiert", () => {
+    const out = applyFormatSpec(
+      { format: "timestamp", locale: "en-US", dateStyle: "long", timeStyle: "short" },
+      instant,
+    );
+    expect(out).toContain("January");
+    expect(out).toContain("2026");
+  });
+
+  test("date mit locale de-DE rendert deutschen Monatsnamen", () => {
+    const out = applyFormatSpec({ format: "date", locale: "de-DE", dateStyle: "long" }, instant);
+    expect(out).toContain("Januar");
+    expect(out).toContain("2026");
+  });
+
+  test("timestamp ohne Optionen nutzt das kompakte Default-Format", () => {
+    const out = applyFormatSpec({ format: "timestamp", locale: "en-US" }, instant);
+    expect(out).toContain("2026");
+    expect(out).not.toBe(instant);
+  });
+
+  test("unparsebarer Wert fällt auf den Rohstring zurück", () => {
+    expect(applyFormatSpec({ format: "timestamp" }, "kein-datum")).toBe("kein-datum");
+    expect(applyFormatSpec({ format: "date" }, "kein-datum")).toBe("kein-datum");
+  });
+});

package/src/format/escape.ts

@@ -6,12 +6,10 @@ export function escapeHtml(s: string): string {
     .replace(/"/g, """);
 }
 
+// Superset of escapeHtml for attribute contexts: additionally escapes ' so
+// single-quoted attributes cannot be broken out of.
 export function escapeHtmlAttr(s: string): string {
-  return s
-    .replace(/&/g, "&")
-    .replace(/"/g, """)
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
+  return escapeHtml(s).replace(/'/g, "&#39;");
 }
 
 export function escapeXml(s: string): string {

package/src/format/index.ts

@@ -39,7 +39,10 @@ export function applyFormatSpec(
   spec: { format: string } & Record<string, unknown>,
   value: unknown,
 ): string {
-  if (value === null || value === undefined || value === "") return "";
+  const isEmpty = value === null || value === undefined || value === "";
+  // priority renders its emptyLabel for empty values — every other format
+  // collapses empty to "".
+  if (isEmpty && spec.format !== "priority") return "";
   switch (spec.format) {
     case "timestamp":
     case "date":
@@ -63,14 +66,14 @@ export function applyFormatSpec(
     case "priority": {
       const emptyLabel = (spec["emptyLabel"] as string | undefined) ?? "—";
       const prefix = (spec["prefix"] as string | undefined) ?? "";
-      if (value === 0 || value === undefined || value === null) return emptyLabel;
+      if (isEmpty || value === 0) return emptyLabel;
       return `${prefix}${value}`;
     }
     default:
       if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
         // biome-ignore lint/suspicious/noConsole: dev-only warning
         console.warn(
-          `[kumiko] applyFormatSpec: unbekannter Format-Key "${spec.format}" — via FieldFormatRegistry module augmentation registriert?`,
+          `[kumiko] applyFormatSpec: unknown format key "${spec.format}" — registered via FieldFormatRegistry module augmentation?`,
         );
       }
       return typeof value === "string" ? value : String(value);

package/src/view-model/edit.ts

@@ -77,6 +77,13 @@ export function computeEditViewModel<
         fieldDef.type === "text"
           ? (fieldDef as unknown as { multiline?: boolean | { rows?: number } }).multiline
           : undefined;
+      // Wall-Clock-Hint bei `type: "timestamp"` mit locatedBy — der
+      // Renderer emittiert dann lokale Zeit ohne `Z` statt UTC-Instant.
+      const wallClock =
+        fieldDef.type === "timestamp" &&
+        (fieldDef as unknown as { locatedBy?: string }).locatedBy !== undefined
+          ? true
+          : undefined;
       // Tier 2.7e-3: Reference-Field — refEntity + refLabelField in
       // das ViewModel reichen damit der Renderer die Lookup-Query
       // bauen kann ohne noch an EntityDefinition zu greifen.
@@ -112,6 +119,7 @@ export function computeEditViewModel<
         ...(options !== undefined && { options }),
         ...(optionLabels !== undefined && { optionLabels }),
         ...(multiline !== undefined && { multiline }),
+        ...(wallClock !== undefined && { wallClock }),
         ...(refEntity !== undefined && { refEntity }),
         ...(refFeature !== undefined && { refFeature }),
         ...(refLabelField !== undefined && { refLabelField }),

package/src/view-model/types.ts

@@ -107,6 +107,10 @@ export type EditFieldViewModel = {
    *  ist — dann rendert der Renderer textarea statt single-line input.
    *  `true` = Default-Zeilen, `{ rows }` = explizite Höhe. */
   readonly multiline?: boolean | { readonly rows?: number };
+  /** Nur bei `type: "timestamp"` gesetzt wenn TimestampFieldDef.locatedBy
+   *  existiert — Wall-Clock-Zeit ohne Offset. Der Renderer emittiert
+   *  dann lokale Zeit ohne `Z` statt eines UTC-Instants. */
+  readonly wallClock?: boolean;
   /** Nur bei `type: "reference"` gesetzt — Tier 2.7e-3.
    *  Die referenced Entity (kurz, ohne feature-prefix). Der Renderer
    *  baut die Query-QN als `<refFeature>:query:<refEntity>:list`. */