@cosmicdrift/kumiko-renderer 0.255.1 → 0.256.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.255.1",
+  "version": "0.256.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.255.1",
-    "@cosmicdrift/kumiko-headless": "0.255.1",
+    "@cosmicdrift/kumiko-framework": "0.256.0",
+    "@cosmicdrift/kumiko-headless": "0.256.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -27,7 +27,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.255.1"
+    "@cosmicdrift/kumiko-locale-de": "0.256.0"
   },
   "repository": {
     "type": "git",

package/src/__tests__/merge-search-params-into-initial.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 import { mergeSearchParamsIntoInitial } from "../app/kumiko-screen";
 
 type FieldDef = {
@@ -121,4 +121,79 @@ describe("mergeSearchParamsIntoInitial", () => {
       mergeSearchParamsIntoInitial(fields, { roles: JSON.stringify(["Admin", "Hacker"]) })["roles"],
     ).toEqual(["Admin"]);
   });
+
+  test("money-type field parses a JSON {amount, currency} param without a defaultCurrency (fw#2763)", () => {
+    const fields: Record<string, FieldDef> = { price: { type: "money" } };
+    const result = mergeSearchParamsIntoInitial(fields, {
+      price: JSON.stringify({ amount: 19.99, currency: "CHF" }),
+    });
+    expect(result["price"]).toEqual({ amount: 19.99, currency: "CHF" });
+  });
+
+  test("money-type field: explicit JSON currency wins over defaultCurrency", () => {
+    const fields: Record<string, FieldDef> = { price: { type: "money" } };
+    const result = mergeSearchParamsIntoInitial(
+      fields,
+      { price: JSON.stringify({ amount: 19.99, currency: "CHF" }) },
+      undefined,
+      "USD",
+    );
+    expect(result["price"]).toEqual({ amount: 19.99, currency: "CHF" });
+  });
+
+  test("money-type field: bare number without a defaultCurrency keeps the number and warns (fw#2763)", () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const fields: Record<string, FieldDef> = { price: { type: "money" } };
+      const result = mergeSearchParamsIntoInitial(fields, { price: "19.99" });
+      expect(result["price"]).toBe(19.99);
+      expect(warnSpy).toHaveBeenCalled();
+      expect(warnSpy.mock.calls[0]?.[0]).toContain("price");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("money-type field: JSON object with a broken shape falls back to the default and warns", () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const fields: Record<string, FieldDef> = {
+        price: { type: "money", default: { amount: 0, currency: "EUR" } },
+      };
+      const result = mergeSearchParamsIntoInitial(fields, { price: JSON.stringify({ amount: 5 }) });
+      expect(result["price"]).toEqual({ amount: 0, currency: "EUR" });
+      expect(warnSpy).toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("money-type field: JSON object with a malformed currency code falls back to the default and warns", () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const fields: Record<string, FieldDef> = {
+        price: { type: "money", default: { amount: 0, currency: "EUR" } },
+      };
+      const result = mergeSearchParamsIntoInitial(fields, {
+        price: JSON.stringify({ amount: 5, currency: "<script>" }),
+      });
+      expect(result["price"]).toEqual({ amount: 0, currency: "EUR" });
+      expect(warnSpy).toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("money-type field: a non-finite bare number falls back to the default (fw#2763)", () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const fields: Record<string, FieldDef> = {
+        price: { type: "money", default: { amount: 0, currency: "EUR" } },
+      };
+      const result = mergeSearchParamsIntoInitial(fields, { price: "1e999" });
+      expect(result["price"]).toEqual({ amount: 0, currency: "EUR" });
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
 });

package/src/__tests__/stringify-nav-params.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { stringifyNavParams } from "../app/row-actions";
+
+describe("stringifyNavParams", () => {
+  test("plain object encodes as JSON (fw#2763)", () => {
+    const result = stringifyNavParams({ price: { amount: 12.5, currency: "EUR" } });
+    expect(result["price"]).toBe(JSON.stringify({ amount: 12.5, currency: "EUR" }));
+  });
+
+  test("array stays JSON", () => {
+    const result = stringifyNavParams({ roles: ["Admin", "User"] });
+    expect(result["roles"]).toBe(JSON.stringify(["Admin", "User"]));
+  });
+
+  test("string, number and boolean stringify via String()", () => {
+    const result = stringifyNavParams({ name: "Alice", age: 42, active: true });
+    expect(result["name"]).toBe("Alice");
+    expect(result["age"]).toBe("42");
+    expect(result["active"]).toBe("true");
+  });
+
+  test("null and undefined become null", () => {
+    const result = stringifyNavParams({ a: null, b: undefined });
+    expect(result["a"]).toBeNull();
+    expect(result["b"]).toBeNull();
+  });
+
+  test("a Date instance stays String(date), not JSON", () => {
+    const date = new Date("2026-01-01T00:00:00.000Z");
+    const result = stringifyNavParams({ createdAt: date });
+    expect(result["createdAt"]).toBe(String(date));
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -337,18 +337,8 @@ function useNavigateToCreateFor(
   return editScreenId !== undefined ? navigate : undefined;
 }
 
-// Initial form values — respect field.default when the entity declares
-// one, otherwise fall back to a type-sane empty value so controlled
-// inputs have something to render. Missing this on booleans/numbers
-// with a `default: true`/`default: 5` would show the form in a state
-// the entity didn't ask for — subtle and easy to miss until a user
-// submits and is surprised.
-// `defaultCurrency` is only passed by entityEdit call sites — the money
-// payload shape it enables (`{amount, currency}`) matches the entity's
-// write schema (schema-builder.ts, kumiko-framework#1923). Callers outside
-// that path (config-edit, action-form) synthesize their own entity and use
-// money as a plain number against a different write contract, so they
-// deliberately keep the old bare-`0` default by omitting the argument.
+// `defaultCurrency` is entityEdit-only — it enables the `{amount, currency}`
+// write shape (fw#1923); config-edit's plain-number contract needs bare `0`.
 export function buildInitialValues(
   fields: Readonly<Record<string, unknown>>,
   defaultCurrency?: string,
@@ -383,6 +373,63 @@ function multiSelectOptionValues(shape: {
   return new Set(shape.options.map((o) => (typeof o === "string" ? o : o.value)));
 }
 
+type MoneyValue = { readonly amount: number; readonly currency: string };
+
+// The currency now comes from a user-controlled URL param and reaches
+// `Intl.NumberFormat`, which throws a RangeError on a malformed code — reject
+// it here instead of crashing the form render.
+const CURRENCY_CODE_PATTERN = /^[A-Za-z]{3}$/;
+
+function isMoneyValue(value: unknown): value is MoneyValue {
+  if (typeof value !== "object" || value === null) return false;
+  const { amount, currency } = value as Partial<MoneyValue>;
+  return (
+    typeof amount === "number" &&
+    Number.isFinite(amount) &&
+    typeof currency === "string" &&
+    CURRENCY_CODE_PATTERN.test(currency)
+  );
+}
+
+function parseJsonOrRaw(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function warnMoneyParam(message: string): void {
+  // biome-ignore lint/suspicious/noConsole: dev-warning for an authoring error
+  console.warn(`[kumiko] ${message}`);
+}
+
+// An actionForm has no entity and thus no defaultCurrency, so a bare-number
+// prefill would stay a number the handler's zod schema rejects (fw#2763).
+function coerceMoneyValue(
+  raw: unknown,
+  fieldName: string,
+  defaultCurrency?: string,
+): MoneyValue | number | undefined {
+  if (raw === null || raw === undefined) return undefined;
+  const value = typeof raw === "string" ? parseJsonOrRaw(raw) : raw;
+  if (value === null) return undefined;
+  if (isMoneyValue(value)) return { amount: value.amount, currency: value.currency.toUpperCase() };
+  if (typeof value === "object") {
+    warnMoneyParam(
+      `money field "${fieldName}" got an object without a usable {amount, currency} shape — the prefill is ignored.`,
+    );
+    return undefined;
+  }
+  const amount = Number(typeof value === "number" ? value : raw);
+  if (!Number.isFinite(amount)) return undefined;
+  if (defaultCurrency !== undefined) return { amount, currency: defaultCurrency };
+  warnMoneyParam(
+    `money field "${fieldName}" was prefilled with a bare number and no currency is available — pass {"amount":<number>,"currency":"<ISO code>"} as the param value, otherwise the handler's schema rejects the submit.`,
+  );
+  return amount;
+}
+
 export function mergeSearchParamsIntoInitial(
   fields: Readonly<Record<string, unknown>>,
   searchParams: Readonly<Record<string, string>>,
@@ -415,12 +462,8 @@ export function mergeSearchParamsIntoInitial(
       const parsed = Number(raw);
       merged[name] = Number.isNaN(parsed) ? defaults[name] : parsed;
     } else if (shape.type === "money") {
-      const parsed = Number(raw);
-      merged[name] = Number.isNaN(parsed)
-        ? defaults[name]
-        : defaultCurrency !== undefined
-          ? { amount: parsed, currency: defaultCurrency }
-          : parsed;
+      const coerced = coerceMoneyValue(raw, name, defaultCurrency);
+      merged[name] = coerced === undefined ? defaults[name] : coerced;
     } else if (shape.type === "boolean") {
       merged[name] = raw === "true";
     } else if (shape.type === "multiSelect") {

package/src/app/row-actions.ts

@@ -81,11 +81,23 @@ export function resolveActionIcon(id: string, declared?: IconKey): IconKey | und
   );
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto: object | null = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
 export function stringifyNavParams(params: Record<string, unknown>): Record<string, string | null> {
   const out: Record<string, string | null> = {};
   for (const [k, v] of Object.entries(params)) {
+    // Structured field values such as money `{amount, currency}` must survive
+    // the URL round-trip as JSON; Date & other class instances stay String().
     out[k] =
-      v === null || v === undefined ? null : Array.isArray(v) ? JSON.stringify(v) : String(v);
+      v === null || v === undefined
+        ? null
+        : Array.isArray(v) || isPlainObject(v)
+          ? JSON.stringify(v)
+          : String(v);
   }
   return out;
 }