@cosmicdrift/kumiko-headless 0.34.2 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.34.2",
+  "version": "0.36.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.21.0",
+    "@cosmicdrift/kumiko-framework": "0.35.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

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

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import { escapeHtml, escapeHtmlAttr, escapeXml } from "../escape";
+
+describe("escapeHtml", () => {
+  test('escapes & < > "', () => {
+    expect(escapeHtml(`& < > "`)).toBe("&amp; &lt; &gt; &quot;");
+  });
+
+  test("does not escape '", () => {
+    expect(escapeHtml("it's")).toBe("it's");
+  });
+
+  test("plain text passes through", () => {
+    expect(escapeHtml("Hello, World!")).toBe("Hello, World!");
+  });
+
+  test("empty string", () => {
+    expect(escapeHtml("")).toBe("");
+  });
+
+  test("multiple occurrences", () => {
+    expect(escapeHtml(`<div class="foo">&bar</div>`)).toBe(
+      "&lt;div class=&quot;foo&quot;&gt;&amp;bar&lt;/div&gt;",
+    );
+  });
+
+  test("no double-escape", () => {
+    const escaped = escapeHtml(`& < > "`);
+    expect(escapeHtml(escaped)).toBe("&amp;amp; &amp;lt; &amp;gt; &amp;quot;");
+  });
+});
+
+describe("escapeHtmlAttr", () => {
+  test('escapes & " < > with priority on & and "', () => {
+    expect(escapeHtmlAttr(`& " < >`)).toBe("&amp; &quot; &lt; &gt;");
+  });
+
+  test("does not escape '", () => {
+    expect(escapeHtmlAttr("it's")).toBe("it's");
+  });
+
+  test("plain attribute value passes through", () => {
+    expect(escapeHtmlAttr("https://example.com?a=1&b=2")).toBe("https://example.com?a=1&amp;b=2");
+  });
+
+  test("empty string", () => {
+    expect(escapeHtmlAttr("")).toBe("");
+  });
+
+  test("no double-escape", () => {
+    const escaped = escapeHtmlAttr(`& " < >`);
+    expect(escapeHtmlAttr(escaped)).toBe("&amp;amp; &amp;quot; &amp;lt; &amp;gt;");
+  });
+});
+
+describe("escapeXml", () => {
+  test("escapes & < > \" '", () => {
+    expect(escapeXml(`& < > " '`)).toBe("&amp; &lt; &gt; &quot; &apos;");
+  });
+
+  test("plain text passes through", () => {
+    expect(escapeXml("Hello, World!")).toBe("Hello, World!");
+  });
+
+  test("empty string", () => {
+    expect(escapeXml("")).toBe("");
+  });
+
+  test("multiple occurrences", () => {
+    expect(escapeXml(`<element attr="value">it's & stuff</element>`)).toBe(
+      "&lt;element attr=&quot;value&quot;&gt;it&apos;s &amp; stuff&lt;/element&gt;",
+    );
+  });
+
+  test("no double-escape", () => {
+    const escaped = escapeXml(`& < > " '`);
+    expect(escapeXml(escaped)).toBe("&amp;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos;");
+  });
+});

package/src/format/escape.ts

@@ -0,0 +1,24 @@
+export function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+export function escapeHtmlAttr(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+export function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}

package/src/format/index.ts

@@ -0,0 +1,78 @@
+// Pure format utilities — no web or platform dependencies.
+// Shared between renderer-web, renderer-native, and server-side tests.
+
+function formatDateCell(
+  value: unknown,
+  type: string,
+  opts?: {
+    locale?: string;
+    dateStyle?: Intl.DateTimeFormatOptions["dateStyle"];
+    timeStyle?: Intl.DateTimeFormatOptions["timeStyle"];
+  },
+): string {
+  try {
+    const raw = typeof value === "string" ? value : String(value);
+    const date = new Date(raw);
+    if (Number.isNaN(date.getTime())) return raw;
+    const locale = opts?.locale;
+    if (opts?.dateStyle || opts?.timeStyle) {
+      return date.toLocaleString(locale, {
+        dateStyle: opts.dateStyle,
+        timeStyle: opts.timeStyle,
+      });
+    }
+    if (type === "date") return date.toLocaleDateString(locale);
+    return date.toLocaleString(locale, {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+  } catch {
+    return String(value);
+  }
+}
+
+export { escapeHtml, escapeHtmlAttr, escapeXml } from "./escape";
+export function applyFormatSpec(
+  spec: { format: string } & Record<string, unknown>,
+  value: unknown,
+): string {
+  if (value === null || value === undefined || value === "") return "";
+  switch (spec.format) {
+    case "timestamp":
+    case "date":
+      return formatDateCell(value, spec.format, {
+        locale: spec["locale"] as string | undefined,
+        dateStyle: spec["dateStyle"] as Intl.DateTimeFormatOptions["dateStyle"],
+        timeStyle:
+          spec.format === "timestamp"
+            ? (spec["timeStyle"] as Intl.DateTimeFormatOptions["timeStyle"])
+            : undefined,
+      });
+    case "boolean": {
+      if (value === true) return (spec["trueLabel"] as string | undefined) ?? "✓";
+      if (value === false) return (spec["falseLabel"] as string | undefined) ?? "";
+      return "";
+    }
+    case "currency": {
+      const sym = (spec["symbol"] as string | undefined) ?? "";
+      return sym.length > 0 ? `${value} ${sym}` : String(value);
+    }
+    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;
+      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?`,
+        );
+      }
+      return typeof value === "string" ? value : String(value);
+  }
+}

package/src/index.ts

@@ -51,6 +51,7 @@ export type {
   SubmitResult,
 } from "./form";
 export { createFormController } from "./form";
+export { applyFormatSpec, escapeHtml, escapeHtmlAttr, escapeXml } from "./format";
 export type {
   NavDefinition,
   NavNode,
@@ -77,6 +78,7 @@ export type {
   ListColumnViewModel,
   ListRowViewModel,
   ListViewModel,
+  RuntimeRenderer,
   ScreenSlots,
   Translate,
 } from "./view-model";

package/src/view-model/__tests__/list.test.ts

@@ -57,7 +57,7 @@ describe("computeListViewModel", () => {
   });
 
   test("object-form column carries renderer through to the view model", () => {
-    const fmt = (v: unknown) => `${v} !`;
+    const fmt = { format: "currency" as const, symbol: "€" };
     const vm = computeListViewModel({
       screen: listScreen([{ field: "title", renderer: fmt }]),
       entity: taskEntity,
@@ -66,7 +66,7 @@ describe("computeListViewModel", () => {
       featureName: "tasks",
     });
 
-    expect(vm.columns[0]?.renderer).toBe(fmt);
+    expect(vm.columns[0]?.renderer).toEqual(fmt);
   });
 
   test("rows map to { id, values } with id pulled from the row", () => {

package/src/view-model/index.ts

@@ -16,6 +16,7 @@ export type {
   ListColumnViewModel,
   ListRowViewModel,
   ListViewModel,
+  RuntimeRenderer,
   ScreenSlots,
   Translate,
 } from "./types";

package/src/view-model/types.ts

@@ -7,6 +7,11 @@ import type {
   ScreenSlots,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 
+// Runtime-only renderer — function form allowed here because the renderer
+// layer (render-list) injects reference-column lookup closures at mount time.
+// Never serialized to JSON.
+export type RuntimeRenderer = (value: unknown, row?: Readonly<Record<string, unknown>>) => string;
+
 // View-Models — plain data structures produced by computeListViewModel and
 // computeEditViewModel. They flatten the combined [screen-def + entity-def
 // + row-data + user] inputs into a shape the renderer draws directly,
@@ -29,12 +34,13 @@ import type {
 // One column, fully resolved. `label` is the localized string the
 // renderer puts in the column header; view-model builder runs it through
 // LocaleResolver.translate() from the i18nKey wired onto the field.
-// `renderer` passes through ScreenDefinition's FieldRenderer verbatim.
+// `renderer` passes through ScreenDefinition's FieldRenderer verbatim; the
+// renderer layer may also inject a RuntimeRenderer closure (reference lookups).
 export type ListColumnViewModel = {
   readonly field: string;
   readonly label: string;
   readonly type: string; // field-type ("text", "number", "money", ...)
-  readonly renderer?: FieldRenderer;
+  readonly renderer?: FieldRenderer | RuntimeRenderer;
   readonly sortable: boolean;
   /** Nur bei `type: "select"` — translated Option-Labels keyed nach raw
    *  value. Renderer rendert `optionLabels[value]` statt humanizeSlug