@cosmicdrift/kumiko-framework 0.34.2 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.34.2",
+  "version": "0.36.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.21.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.35.0",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"

package/src/engine/__tests__/build-app-schema.test.ts

@@ -151,4 +151,86 @@ describe("buildAppSchema", () => {
     // Feature-namen identisch nach Roundtrip
     expect(parsed.features[0].featureName).toBe("ent");
   });
+
+  test("FormatSpec-Renderer + FieldCondition-RowActions überleben JSON-Roundtrip unverändert", () => {
+    // Pinnt: FormatSpec ({ format: "timestamp" } etc.) ist JSON-sicher
+    // und FieldCondition ({ field, eq/ne } | boolean) bleibt nach
+    // JSON.parse(JSON.stringify(app)) deep-equal zum Original.
+    const entity = {
+      table: "events",
+      fields: {
+        id: { type: "text" },
+        startedAt: { type: "timestamp" },
+        status: { type: "text" },
+        priority: { type: "number" },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ev", (r) => {
+      r.entity("event", entity);
+      r.screen({
+        id: "list",
+        type: "entityList",
+        entity: "event",
+        columns: [
+          "id",
+          { field: "startedAt", renderer: { format: "timestamp" as const } },
+          { field: "priority", renderer: { format: "priority" as const, prefix: "P" } },
+          { field: "status" },
+        ],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "open",
+            label: "Öffnen",
+            screen: "detail",
+            visible: { field: "status", ne: "archived" },
+          },
+          {
+            kind: "navigate",
+            id: "archive",
+            label: "Archivieren",
+            screen: "archive",
+            visible: { field: "status", eq: "open" },
+          },
+          {
+            kind: "navigate",
+            id: "always",
+            label: "Immer",
+            screen: "view",
+            visible: true,
+          },
+        ],
+      });
+    });
+
+    const app = buildAppSchema(createRegistry([f]));
+    const roundTripped = JSON.parse(JSON.stringify(app));
+
+    // Vollständige deep-equality — kein Silent-Drop durch JSON.stringify
+    expect(roundTripped).toEqual(app);
+
+    // Explizit: FormatSpec-Felder landen unverändert an
+    const screen = roundTripped.features[0]?.screens[0];
+    const cols = screen?.columns as Array<{ field?: string; renderer?: unknown }>;
+    expect(cols?.find((c) => c.field === "startedAt")?.renderer).toEqual({
+      format: "timestamp",
+    });
+    expect(cols?.find((c) => c.field === "priority")?.renderer).toEqual({
+      format: "priority",
+      prefix: "P",
+    });
+
+    // Explizit: FieldCondition-Varianten (eq, ne, boolean) landen unverändert an
+    const actions = screen?.rowActions as Array<{ id: string; visible?: unknown }>;
+    expect(actions?.find((a) => a.id === "open")?.visible).toEqual({
+      field: "status",
+      ne: "archived",
+    });
+    expect(actions?.find((a) => a.id === "archive")?.visible).toEqual({
+      field: "status",
+      eq: "open",
+    });
+    expect(actions?.find((a) => a.id === "always")?.visible).toBe(true);
+  });
 });

package/src/engine/build-app-schema.ts

@@ -59,10 +59,31 @@ export function buildAppSchema(registry: Registry): AppSchema {
     }
   }
 
-  return {
+  const schema = {
     features,
     ...(workspaces.length > 0 && { workspaces }),
   };
+
+  if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+    try {
+      const roundTripped = JSON.parse(JSON.stringify(schema));
+      if (JSON.stringify(roundTripped) !== JSON.stringify(schema)) {
+        // biome-ignore lint/suspicious/noConsole: dev-only assertion
+        console.error(
+          "[kumiko] buildAppSchema: Output ist nicht JSON-safe — ein Funktions-Renderer oder nicht-serialisierbarer Wert ist in das Schema gerutscht. Details im Diff:",
+          schema,
+        );
+      }
+    } catch {
+      // biome-ignore lint/suspicious/noConsole: dev-only assertion
+      console.error(
+        "[kumiko] buildAppSchema: JSON.stringify fehlgeschlagen — Schema enthält nicht-serialisierbare Werte.",
+        schema,
+      );
+    }
+  }
+
+  return schema;
 }
 
 function projectEntities(

package/src/engine/types/index.ts

@@ -213,7 +213,9 @@ export type {
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FieldCondition,
+  FieldFormatRegistry,
   FieldRenderer,
+  FormatSpec,
   ListColumnSpec,
   PlatformComponent,
   RowAction,
@@ -225,7 +227,12 @@ export type {
   ScreenSlots,
   ToolbarAction,
 } from "./screen";
-export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./screen";
+export {
+  isExtensionEditSection,
+  isFormatSpec,
+  normalizeEditField,
+  normalizeListColumn,
+} from "./screen";
 export type { TargetRef } from "./target-ref";
 export type {
   Subscribe,

package/src/engine/types/screen.ts

@@ -24,18 +24,38 @@ export type PlatformComponent = {
   readonly native?: unknown;
 };
 
+// Built-in value formatters. Apps extend via module augmentation:
+//   declare module "@cosmicdrift/kumiko-framework" {
+//     interface FieldFormatRegistry { myFormat: { myOption?: string } }
+//   }
+// renderer-web handles all built-in keys; unknown app-specific keys fall back
+// to String(value).
+export interface FieldFormatRegistry {
+  timestamp: {
+    readonly locale?: string;
+    readonly dateStyle?: "full" | "long" | "medium" | "short";
+    readonly timeStyle?: "full" | "long" | "medium" | "short";
+  };
+  date: {
+    readonly locale?: string;
+    readonly dateStyle?: "full" | "long" | "medium" | "short";
+  };
+  boolean: { readonly trueLabel?: string; readonly falseLabel?: string };
+  currency: { readonly symbol?: string };
+  priority: { readonly emptyLabel?: string; readonly prefix?: string };
+}
+
+// Discriminated union derived from the registry — one variant per key.
+// JSON-safe: no function members, survives buildAppSchema → window.__KUMIKO_SCHEMA__.
+export type FormatSpec = {
+  [K in keyof FieldFormatRegistry]: { readonly format: K } & FieldFormatRegistry[K];
+}[keyof FieldFormatRegistry];
+
 // Level-2 field renderer (ui-architecture.md §Renderer Customization):
 //   - PlatformComponent → platform-specific component from the same feature
-//   - string            → cross-feature QN reference (resolved by the renderer)
-//   - function          → inline value formatter (e.g. `v => `${v} €``)
-// Function-Form bekommt optional die ganze Row als 2. Argument —
-// nützlich für context-aware Renderer (Tier 2.7e-Eagerload nutzt das
-// um aus row._refs den resolved Display-Wert zu lesen). Renderer die
-// nur den value brauchen ignorieren das Argument einfach.
-export type FieldRenderer =
-  | PlatformComponent
-  | string
-  | ((value: unknown, row?: Readonly<Record<string, unknown>>) => string);
+//   - string            → cross-feature QN reference (resolved at mount-time)
+//   - FormatSpec        → declarative value formatter, JSON-safe ({ format: "timestamp" } etc.)
+export type FieldRenderer = PlatformComponent | string | FormatSpec;
 
 // Declarative field-state condition. Evaluated by the renderer against the
 // current row/form values. Three forms:
@@ -465,11 +485,35 @@ export type ScreenDefinition =
   | ConfigEditScreenDefinition
   | CustomScreenDefinition;
 
+// Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
+// authors who branch on the three FieldRenderer variants without manual
+// "format" in renderer checks.
+export function isFormatSpec(r: unknown): r is FormatSpec {
+  return (
+    typeof r === "object" &&
+    r !== null &&
+    "format" in r &&
+    typeof (r as Record<string, unknown>)["format"] === "string"
+  );
+}
+
 // Collapse the string-shorthand into the object form. Both the boot-validator
 // and (later) ui-core's view-model builder iterate over fields/columns — the
 // helper keeps that loop from growing two branches everywhere.
 export function normalizeListColumn(c: ListColumnSpec): Exclude<ListColumnSpec, string> {
-  return typeof c === "string" ? { field: c } : c;
+  const col = typeof c === "string" ? { field: c } : c;
+  if (
+    typeof process !== "undefined" &&
+    process.env.NODE_ENV !== "production" &&
+    col.renderer !== undefined &&
+    typeof col.renderer === "function"
+  ) {
+    // biome-ignore lint/suspicious/noConsole: dev-only warning
+    console.warn(
+      `[kumiko] normalizeListColumn: Feld "${col.field}" hat einen Funktions-Renderer — dieser wird von JSON.stringify verworfen. Bitte auf FormatSpec ({ format: "..." }) migrieren.`,
+    );
+  }
+  return col;
 }
 
 export function normalizeEditField(f: EditFieldSpec): Exclude<EditFieldSpec, string> {

package/src/ui-types/index.ts

@@ -69,6 +69,7 @@ export type {
 } from "../engine/types/screen";
 export {
   isExtensionEditSection,
+  isFormatSpec,
   normalizeEditField,
   normalizeListColumn,
 } from "../engine/types/screen";