@cosmicdrift/kumiko-renderer 1.0.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "1.0.0",
+  "version": "2.0.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,9 +15,10 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "1.0.0",
-    "@cosmicdrift/kumiko-headless": "1.0.0",
-    "react": "^19.2.6"
+    "@cosmicdrift/kumiko-framework": "2.0.0",
+    "@cosmicdrift/kumiko-headless": "2.0.0",
+    "react": "^19.2.6",
+    "temporal-polyfill": "^0.3.2"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",

package/src/__tests__/error-i18n-defaults.test.ts

@@ -56,4 +56,17 @@ describe("kumikoDefaultTranslations covers every error i18nKey", () => {
     expect(de?.["errors.download.urlMissing"]).toBeTruthy();
     expect(en?.["errors.download.urlMissing"]).toBeTruthy();
   });
+
+  // Client-emitted (dispatcher-live error-mapping) — network/abort never
+  // reach the server, so no error class mints these; still rendered through
+  // this last-resort bundle whenever a feature reads res.error.i18nKey raw.
+  test("dispatcher.errors.network has de+en default", () => {
+    expect(de?.["dispatcher.errors.network"]).toBeTruthy();
+    expect(en?.["dispatcher.errors.network"]).toBeTruthy();
+  });
+
+  test("dispatcher.errors.aborted has de+en default", () => {
+    expect(de?.["dispatcher.errors.aborted"]).toBeTruthy();
+    expect(en?.["dispatcher.errors.aborted"]).toBeTruthy();
+  });
 });

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

@@ -0,0 +1,12 @@
+import { describe, expect, test } from "bun:test";
+import { formatWhen } from "../format-when";
+
+describe("formatWhen", () => {
+  test("formats a parseable ISO timestamp", () => {
+    expect(formatWhen("2024-01-01T00:00:00.000Z")).not.toBe("2024-01-01T00:00:00.000Z");
+  });
+
+  test("falls back to the raw value on an unparseable input", () => {
+    expect(formatWhen("garbage")).toBe("garbage");
+  });
+});

package/src/__tests__/i18n.test.tsx

@@ -6,6 +6,7 @@ import {
   createStaticLocaleResolver,
   LocaleProvider,
   type TranslationsByLocale,
+  translationsByLocaleFromKeys,
   useLocale,
   useTranslation,
 } from "../i18n";
@@ -105,6 +106,64 @@ describe("useTranslation — re-render on locale change", () => {
     expect(getByTestId("msg").textContent).toBe("Hello");
   });
 });
+describe("useTranslation — referential stability", () => {
+  // Prod-Incident 2026-07-07: admin-shell Overview-Screens hatten `t` in
+  // einem useEffect-Dependency-Array. Ein neues `t` pro Render triggerte
+  // einen Render/Effect-Endlos-Loop (~600 Queries/Sekunde). `t` (und der
+  // gesamte Context-Value) MUSS über Re-Renders hinweg stabil bleiben,
+  // solange sich Resolver/Bundles/Locale nicht ändern.
+  test("t keeps the same reference across re-renders when nothing changed", () => {
+    const resolver = createStaticLocaleResolver({ locale: "de" });
+    const { result, rerender } = renderHook(() => useTranslation(), {
+      wrapper: wrap(resolver),
+    });
+    const firstT = result.current;
+    rerender();
+    expect(result.current).toBe(firstT);
+  });
+  test("t stays stable across parent re-renders even with a fresh fallbackBundles literal per parent-render", () => {
+    // Realistischer Fall: eine App übergibt `fallbackBundles={[...]}` als
+    // Inline-Literal. Ohne Provider-seitige Memoization würde jeder
+    // Ahnen-Re-Render den Context-Value neu bauen. Hier prüfen wir nur
+    // den Provider-internen Memoization-Pfad bei stabilen Props.
+    const resolver = createStaticLocaleResolver({ locale: "de" });
+    const bundles: TranslationsByLocale[] = [{ de: { greet: "Hallo" } }];
+    function Probe(): ReactNode {
+      const t = useTranslation();
+      (Probe as unknown as { lastT?: unknown }).lastT = t;
+      return null;
+    }
+    const { rerender } = render(
+      <LocaleProvider resolver={resolver} fallbackBundles={bundles}>
+        <Probe />
+      </LocaleProvider>,
+    );
+    const firstT = (Probe as unknown as { lastT?: unknown }).lastT;
+    rerender(
+      <LocaleProvider resolver={resolver} fallbackBundles={bundles}>
+        <Probe />
+      </LocaleProvider>,
+    );
+    expect((Probe as unknown as { lastT?: unknown }).lastT).toBe(firstT);
+  });
+});
+describe("translationsByLocaleFromKeys", () => {
+  test("pivots key-first source to locale-first bundles losslessly", () => {
+    const source = {
+      "app:nav.home": { de: "Start", en: "Home" },
+      "app:nav.settings": { de: "Einstellungen", en: "Settings" },
+    };
+    const byLocale = translationsByLocaleFromKeys(source);
+    expect(byLocale["de"]).toEqual({
+      "app:nav.home": "Start",
+      "app:nav.settings": "Einstellungen",
+    });
+    expect(byLocale["en"]).toEqual({
+      "app:nav.home": "Home",
+      "app:nav.settings": "Settings",
+    });
+  });
+});
 describe("useLocale", () => {
   test("returns the resolver", () => {
     const resolver = createStaticLocaleResolver({ locale: "de" });

package/src/__tests__/qn.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { lastSegment } from "../app/qn";
+import { toKebab as serverToKebab } from "@cosmicdrift/kumiko-framework/engine";
+import { lastSegment, toKebab } from "../app/qn";
 
 describe("lastSegment", () => {
   test("strips feature-prefix from screen-QN", () => {
@@ -38,3 +39,45 @@ describe("lastSegment", () => {
     expect(lastSegment("publicstatus:screen:")).toBe("");
   });
 });
+
+describe("toKebab", () => {
+  test("camelCase entity ids match server qualifyEntityName", () => {
+    expect(toKebab("driverModel")).toBe("driver-model");
+    expect(toKebab("statementUpload")).toBe("statement-upload");
+  });
+
+  test("already kebab unchanged", () => {
+    expect(toKebab("driver-model")).toBe("driver-model");
+  });
+
+  test("preserves colon segments", () => {
+    expect(toKebab("driverModel:list")).toBe("driver-model:list");
+  });
+
+  test("consecutive uppercase (acronym boundary)", () => {
+    expect(toKebab("SSEBroadcast")).toBe("sse-broadcast");
+  });
+
+  test("dot separators become dashes", () => {
+    expect(toKebab("billing-period.create")).toBe("billing-period-create");
+  });
+
+  // Drift guard: this file is a byte-identical copy of the server's toKebab
+  // (packages/framework/src/engine/qualified-name.ts) kept in sync only by
+  // convention/comment, not by import (avoids pulling server deps into the
+  // browser bundle). Table-driven against the server's own doc examples so a
+  // future edit to either copy that breaks parity fails loudly here.
+  test("matches the server implementation for its documented examples", () => {
+    const cases = [
+      "task.create",
+      "ticketAssigned",
+      "billing-period.create",
+      "monthlyReport",
+      "SSEBroadcast",
+      "driverModel:list",
+    ];
+    for (const input of cases) {
+      expect(toKebab(input)).toBe(serverToKebab(input));
+    }
+  });
+});

package/src/__tests__/sort-by-accessor.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+import { sortByAccessor } from "../sort-by-accessor";
+
+type Row = { readonly name: string; readonly count: number };
+
+function makeRows(): readonly Row[] {
+  return [
+    { name: "b", count: 2 },
+    { name: "a", count: 3 },
+    { name: "c", count: 1 },
+  ];
+}
+
+const accessors = {
+  name: (r: Row) => r.name,
+  count: (r: Row) => r.count,
+};
+
+describe("sortByAccessor", () => {
+  test("sort === null returns rows unchanged (same reference)", () => {
+    const rows = makeRows();
+    expect(sortByAccessor(rows, null, accessors)).toBe(rows);
+  });
+
+  test("an unknown field returns rows unchanged (same reference)", () => {
+    const rows = makeRows();
+    expect(sortByAccessor(rows, { field: "nope", dir: "asc" }, accessors)).toBe(rows);
+  });
+
+  test("sorts ascending by the given accessor", () => {
+    const rows = makeRows();
+    const sorted = sortByAccessor(rows, { field: "name", dir: "asc" }, accessors);
+    expect(sorted.map((r) => r.name)).toEqual(["a", "b", "c"]);
+  });
+
+  test("sorts descending by the given accessor", () => {
+    const rows = makeRows();
+    const sorted = sortByAccessor(rows, { field: "count", dir: "desc" }, accessors);
+    expect(sorted.map((r) => r.count)).toEqual([3, 2, 1]);
+  });
+
+  test("does not mutate the input array", () => {
+    const rows = makeRows();
+    const original = [...rows];
+    sortByAccessor(rows, { field: "name", dir: "asc" }, accessors);
+    expect(rows).toEqual(original);
+  });
+});

package/src/app/__tests__/config-edit-shim.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import type { ConfigEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { synthesizeConfigEditEntity, synthesizeConfigEditScreen } from "../config-edit-shim";
+
+describe("synthesizeConfigEditEntity", () => {
+  test("wraps the inline fields as an EntityDefinition", () => {
+    const fields = { apiKey: { type: "text" } } as unknown as ConfigEditScreenDefinition["fields"];
+    expect(synthesizeConfigEditEntity(fields)).toEqual({ fields });
+  });
+});
+
+describe("synthesizeConfigEditScreen", () => {
+  test("stamps type: entityEdit and a pseudo entity name", () => {
+    const screen = {
+      id: "settings",
+      layout: { sections: [] },
+    } as unknown as ConfigEditScreenDefinition;
+
+    const result = synthesizeConfigEditScreen(screen);
+    expect(result.id).toBe("settings");
+    expect(result.type).toBe("entityEdit");
+    expect(result.entity).toBe("__config-edit__");
+    expect(result.layout).toBe(screen.layout);
+    expect(result).not.toHaveProperty("fieldLabels");
+    expect(result).not.toHaveProperty("access");
+  });
+
+  test("carries fieldLabels and access through when present", () => {
+    const screen = {
+      id: "settings",
+      layout: { sections: [] },
+      fieldLabels: { apiKey: "config.apiKey" },
+      access: { roles: ["Admin"] },
+    } as unknown as ConfigEditScreenDefinition;
+
+    const result = synthesizeConfigEditScreen(screen);
+    expect(result.fieldLabels).toEqual({ apiKey: "config.apiKey" });
+    expect(result.access).toEqual({ roles: ["Admin"] });
+  });
+});

package/src/app/__tests__/screen-access-allows.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { screenAccessAllows } from "../kumiko-screen";
+
+describe("screenAccessAllows", () => {
+  test("allows when no access rule is set", () => {
+    expect(screenAccessAllows(undefined, undefined)).toBe(true);
+  });
+
+  test("openToAll: true allows regardless of roles", () => {
+    expect(screenAccessAllows({ openToAll: true }, undefined)).toBe(true);
+  });
+
+  test("roles-gated allows a matching role", () => {
+    expect(screenAccessAllows({ roles: ["Admin"] }, ["Admin"])).toBe(true);
+  });
+
+  test("roles-gated denies with no matching role", () => {
+    expect(screenAccessAllows({ roles: ["Admin"] }, ["Member"])).toBe(false);
+  });
+
+  test("roles-gated denies when userRoles is undefined", () => {
+    expect(screenAccessAllows({ roles: ["Admin"] }, undefined)).toBe(false);
+  });
+});

package/src/app/dashboard-body.tsx

@@ -0,0 +1,32 @@
+// Dashboard-Body-Injection: der KumikoScreen-Switch ist plattform-agnostisch,
+// die Dashboard-Panels (StatCard, Charts) sind es nicht — die Implementierung
+// kommt vom Platform-Package (renderer-web registriert seine Web-Variante in
+// createKumikoApp). Gleiches Muster wie CustomScreensProvider.
+
+import type { DashboardScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Translate } from "@cosmicdrift/kumiko-headless";
+import { type ComponentType, createContext, type ReactNode, useContext } from "react";
+
+export type DashboardBodyProps = {
+  readonly screen: DashboardScreenDefinition;
+  readonly translate?: Translate;
+};
+
+const DashboardBodyContext = createContext<ComponentType<DashboardBodyProps> | undefined>(
+  undefined,
+);
+
+export type DashboardBodyProviderProps = {
+  readonly children: ReactNode;
+  readonly value: ComponentType<DashboardBodyProps>;
+};
+
+export function DashboardBodyProvider({ children, value }: DashboardBodyProviderProps): ReactNode {
+  return <DashboardBodyContext.Provider value={value}>{children}</DashboardBodyContext.Provider>;
+}
+
+/** Undefined wenn kein Platform-Package einen Dashboard-Body registriert
+ *  hat — KumikoScreen zeigt dann seinen Placeholder-Banner. */
+export function useDashboardBody(): ComponentType<DashboardBodyProps> | undefined {
+  return useContext(DashboardBodyContext);
+}

package/src/app/extension-sections.tsx

@@ -1,8 +1,9 @@
 // Extension-Section-Components-Map: client-side Lookup für entityEdit
-// sections vom Type `extension`. RenderEdit schaut hier nach dem
-// `__component`-Namen aus section.component und mountet die passende
-// Component mit { entityName, entityId } — die Bundled-Feature-Component
-// lädt + persistiert dann ihre eigenen Daten (z.B. custom-fields).
+// sections vom Type `extension`, List-Header-Slots UND Dashboard-`custom`-
+// Panels. Jeder Mount-Ort löst den `__component`-Namen aus einer
+// PlatformComponent über dieselbe Registry auf und mountet die passende
+// Component — die Bundled-Feature-/App-Component lädt + persistiert dann
+// ihre eigenen Daten (z.B. custom-fields, oder ein eigenständiger Chart).
 //
 // Mounting analog zu CustomScreensProvider — createKumikoApp im
 // renderer-web sammelt alle clientFeatures.extensionSectionComponents und
@@ -39,6 +40,12 @@ export type ExtensionSectionProps = {
    *  (useListUrlState) ansprechen kann — z.B. ein Tag-Filter der die Liste auf
    *  eine id-Menge narrowed. In entityEdit-Sections undefined. */
   readonly screenId?: string;
+  /** Nur im Dashboard-`custom`-Panel gesetzt: der aktuell gewählte Wert des
+   *  Screen-Filters (siehe DashboardFilterDefinition), gemerged wie bei jeder
+   *  anderen Panel-Query. In allen anderen Mount-Orten undefined. Dashboard-
+   *  Panels haben keine Entity — entityName/entityId tragen dort die
+   *  screen.id bzw. null, siehe CustomPanelBody in dashboard-body.tsx. */
+  readonly filterParams?: Readonly<Record<string, unknown>>;
 };
 
 export type ExtensionSectionComponent = ComponentType<ExtensionSectionProps>;