@cosmicdrift/kumiko-framework 0.32.1 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.32.1",
+  "version": "0.34.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>",

package/src/engine/__tests__/boot-validator.test.ts

@@ -1854,6 +1854,110 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- rowAction kind="writeHandler" handler-QN-Validierung (Tier 2.7e-1 erw.) ---
+  describe("entityList rowAction kind=writeHandler handler-QN", () => {
+    function makeFeature(handlerQn: string, register: boolean) {
+      return defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [{ id: "delete", label: "actions.delete", handler: handlerQn }],
+        });
+        if (register) {
+          r.writeHandler(
+            "delete",
+            z.object({}),
+            async () => ({ isSuccess: true as const, data: null }),
+            {
+              access: { roles: ["Admin"] },
+            },
+          );
+        }
+      });
+    }
+
+    test("handler → registriert → kein Throw", () => {
+      expect(() => validateBoot([makeFeature("shop:write:delete", true)])).not.toThrow();
+    });
+
+    test("handler → nicht registriert → Throw mit klarer Message", () => {
+      expect(() => validateBoot([makeFeature("shop:write:ghost", false)])).toThrow(
+        /rowAction "delete" .*handler "shop:write:ghost" is not a registered write-handler/,
+      );
+    });
+  });
+
+  // --- toolbarAction navigate + writeHandler Validierung (Tier 2.7e-2) ---
+  describe("entityList toolbarAction navigate (Tier 2.7e-2)", () => {
+    function makeFeature(targetScreen: string, withTarget: boolean) {
+      return defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          toolbarActions: [
+            { kind: "navigate", id: "open-form", label: "actions.open", screen: targetScreen },
+          ],
+        });
+        if (withTarget) {
+          r.screen({ id: targetScreen, type: "custom", renderer: { react: "stub" } });
+        }
+      });
+    }
+
+    test("navigate-target → registriert → kein Throw", () => {
+      expect(() => validateBoot([makeFeature("product-form", true)])).not.toThrow();
+    });
+
+    test("navigate-target → unbekannt → Throw mit klarer Message", () => {
+      expect(() => validateBoot([makeFeature("ghost-form", false)])).toThrow(
+        /toolbarAction "open-form" navigate-target "ghost-form" does not resolve/,
+      );
+    });
+  });
+
+  describe("entityList toolbarAction writeHandler handler-QN (Tier 2.7e-2)", () => {
+    function makeFeature(handlerQn: string, register: boolean) {
+      return defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          toolbarActions: [
+            { kind: "writeHandler", id: "sync", label: "actions.sync", handler: handlerQn },
+          ],
+        });
+        if (register) {
+          r.writeHandler(
+            "sync",
+            z.object({}),
+            async () => ({ isSuccess: true as const, data: null }),
+            {
+              access: { roles: ["Admin"] },
+            },
+          );
+        }
+      });
+    }
+
+    test("handler → registriert → kein Throw", () => {
+      expect(() => validateBoot([makeFeature("shop:write:sync", true)])).not.toThrow();
+    });
+
+    test("handler → nicht registriert → Throw mit klarer Message", () => {
+      expect(() => validateBoot([makeFeature("shop:write:ghost", false)])).toThrow(
+        /toolbarAction "sync" .*handler "shop:write:ghost" is not a registered write-handler/,
+      );
+    });
+  });
+
   // --- defaultSort funktioniert für ALLE Field-Types die sortable
   //     unterstützen (Tier 2.6b Field-Erweiterung) ---
   // Vor Tier 2.6b war `sortable` nur auf TextFieldDef. Erweitert auf

package/src/engine/__tests__/screen.test.ts

@@ -42,10 +42,7 @@ describe("r.screen() — registration", () => {
             {
               title: "shop:section.basics",
               columns: 2,
-              fields: [
-                "name",
-                { field: "sku", readOnly: (data) => Boolean((data as { sku?: string }).sku) },
-              ],
+              fields: ["name", { field: "sku", readOnly: { field: "sku", ne: null } }],
             },
           ],
         },
@@ -358,7 +355,7 @@ describe("validateBoot — screen validation", () => {
             {
               title: "shop:section.basics",
               columns: 2,
-              fields: ["name", { field: "sku", visible: () => true, required: () => true }],
+              fields: ["name", { field: "sku", visible: true, required: true }],
             },
           ],
         },

package/src/engine/boot-validator/screens-nav.ts

@@ -345,19 +345,51 @@ export function validateScreens(
           );
         }
       }
-      // Tier 2.7e-1: rowActions mit kind:"navigate" pinst dass das
-      // referenced screen tatsächlich existiert (selbes Feature). Ein
-      // typo'd target landet sonst beim Klick als "Screen not found"-
-      // Banner.
+      // Tier 2.7e-1: rowActions pinnen — navigate-target existiert (selbes
+      // Feature), writeHandler-QN ist registriert. Tippfehler fallen sonst
+      // erst beim ersten Klick als "Screen not found" / 404 auf.
       if (screen.rowActions !== undefined) {
         for (const action of screen.rowActions) {
-          if (action.kind !== "navigate") continue;
-          const candidateQn = qualifyEntityName(feature.name, "screen", action.screen);
-          if (!allScreenQns.has(candidateQn)) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (entityList) rowAction "${action.id}" ` +
-                `navigate-target "${action.screen}" does not resolve to a registered screen in this feature.`,
-            );
+          if (action.kind === "navigate") {
+            const candidateQn = qualifyEntityName(feature.name, "screen", action.screen);
+            if (!allScreenQns.has(candidateQn)) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (entityList) rowAction "${action.id}" ` +
+                  `navigate-target "${action.screen}" does not resolve to a registered screen in this feature.`,
+              );
+            }
+          } else {
+            if (!allWriteHandlerQns.has(action.handler)) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (entityList) rowAction "${action.id}" ` +
+                  `handler "${action.handler}" is not a registered write-handler. Check the QN spelling ` +
+                  `(expected "<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`,
+              );
+            }
+          }
+        }
+      }
+      // Tier 2.7e-2: toolbarActions — analog zu rowActions, aber bisher
+      // ohne Validator. Typo'd navigate-targets und unregistrierte
+      // writeHandler-QNs fallen bis hierhin erst beim Klick auf.
+      if (screen.toolbarActions !== undefined) {
+        for (const action of screen.toolbarActions) {
+          if (action.kind === "navigate") {
+            const candidateQn = qualifyEntityName(feature.name, "screen", action.screen);
+            if (!allScreenQns.has(candidateQn)) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (entityList) toolbarAction "${action.id}" ` +
+                  `navigate-target "${action.screen}" does not resolve to a registered screen in this feature.`,
+              );
+            }
+          } else {
+            if (!allWriteHandlerQns.has(action.handler)) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (entityList) toolbarAction "${action.id}" ` +
+                  `handler "${action.handler}" is not a registered write-handler. Check the QN spelling ` +
+                  `(expected "<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`,
+              );
+            }
           }
         }
       }

package/src/engine/types/screen.ts

@@ -37,13 +37,16 @@ export type FieldRenderer =
   | string
   | ((value: unknown, row?: Readonly<Record<string, unknown>>) => string);
 
-// Conditional field-state evaluator. `data` is the current form row and
-// `ctx` carries user / session info — the form-controller in ui-core passes
-// both at evaluation time. Engine-side defaults are `unknown` because the
-// framework has nothing to assert about the shapes; feature code can narrow
-// them by passing type args (e.g. `FieldCondition<OrderRow>`) to skip the
-// cast at call sites.
-export type FieldCondition<TData = unknown, TCtx = unknown> = (data: TData, ctx: TCtx) => boolean;
+// Declarative field-state condition. Evaluated by the renderer against the
+// current row/form values. Three forms:
+//   boolean          — static on/off (e.g. readOnly: true)
+//   { field, eq }    — true when row[field] === eq
+//   { field, ne }    — true when row[field] !== ne
+// JSON-safe: survives buildAppSchema → window.__KUMIKO_SCHEMA__ stringify.
+export type FieldCondition =
+  | boolean
+  | { readonly field: string; readonly eq: unknown }
+  | { readonly field: string; readonly ne: unknown };
 
 // --- entityList ---
 
@@ -108,31 +111,31 @@ export type ScreenFilter = {
   readonly value: unknown;
 };
 
+/** Deklarativer Row-Field-Extraktor — JSON-sicher (kein Function-Prop,
+ *  überlebt window.__KUMIKO_SCHEMA__ / buildAppSchema).
+ *
+ *  `pick`: extrahiert Felder 1:1. `{ pick: ["id", "version"] }` → `{ id: row.id, version: row.version }`
+ *  `map`:  benennt um.        `{ map: { incidentId: "id" } }` → `{ incidentId: row.id }`
+ *
+ *  Limitation: computed/template-Werte können nicht ausgedrückt werden
+ *  — solche Logik gehört server-side in den Write-Handler. */
+export type RowFieldExtractor =
+  | { readonly pick: readonly string[] }
+  | { readonly map: Readonly<Record<string, string>> };
+
 // RowAction — per-Row Button/Dropdown-Item das einen Write-Handler
-// triggert. Lebt im Schema (Author deklariert pro List-Screen welche
-// Aktionen möglich sind), Caller liefert die handler-QN + optional
-// payload-Builder + Confirm-Prompt.
+// triggert oder zu einem anderen Screen navigiert.
 //
 // Pattern: row-level Lifecycle-Operations (Maintenance start/cancel/
 // complete, Incident resolve, Order ship etc.) — Sachen die in einem
 // CRUD-update kein passendes Verb haben aber als WriteHandler existieren.
 //
-// ⚠️ Function-Props (`payload`, `params`, `visible`) leben nur im
-// Monolith-Bundle-Pattern (Server + Client teilen Source-Bundle, wie
-// Showcase mit dev-server). In setups mit JSON-injected window.__
-// KUMIKO_SCHEMA__ werden Functions silent gedroppt (`buildAppSchema`
-// whitelist-projeziert + JSON.stringify entfernt sie). Für solche Apps:
-//   - `payload`/`params` weglassen → Default `{ id: row.id }` greift.
-//   - `visible` über server-side Filter im Handler statt Client-side
-//     Visibility lösen.
-// Declarative Alternative kommt wenn ein konkreter Use-Case das fordert.
-//
 // Discriminated Union mit `kind`:
-//   - "writeHandler" (default für Backwards-Compat): dispatched einen
-//     Write-Handler mit Payload pro Row.
+//   - "writeHandler" (default): dispatched einen Write-Handler mit
+//     Payload pro Row.
 //   - "navigate" (Tier 2.7e): navigiert zu einem anderen Screen,
-//     optional mit URL-Search-Params aus `params(row)`. Use-case:
-//     "Edit", "View Audit-Log", "Open in actionForm" etc.
+//     optional mit URL-Search-Params aus `params`. Use-case: "Edit",
+//     "View Audit-Log", "Open in actionForm" etc.
 export type RowAction = RowActionWriteHandler | RowActionNavigate;
 
 export type RowActionWriteHandler = {
@@ -147,9 +150,9 @@ export type RowActionWriteHandler = {
    *  "publicstatus:write:maintenance:start". Wird via useDispatcher
    *  dispatcht. */
   readonly handler: string;
-  /** Payload-Builder pro Row. Default = `{ id: row.id }`. ⚠️ Function-
-   *  Form nur im Monolith-Bundle-Pattern — siehe Type-Header. */
-  readonly payload?: (row: Readonly<Record<string, unknown>>) => Record<string, unknown>;
+  /** Deklarativer Payload pro Row. Default = `{ id: row.id }`.
+   *  `pick` extrahiert Felder gleichen Namens; `map` benennt um. */
+  readonly payload?: RowFieldExtractor;
   /** i18n-Key für die Confirm-Dialog-Description. Wenn gesetzt, öffnet
    *  ein Modal vor der Ausführung — der User muss explizit bestätigen.
    *  Zusammen mit `style: "danger"` ist das die Standard-Sicherheits-
@@ -160,10 +163,7 @@ export type RowActionWriteHandler = {
    *  Action einen langen Namen hat ("Mark Subscription as Cancelled")
    *  und der Button kürzer sein soll ("Cancel Subscription"). */
   readonly confirmLabel?: string;
-  /** Conditional Visibility pro Row — Action erscheint nur wenn die
-   *  Bedingung true returnt. Beispiel: nur "Start" zeigen wenn
-   *  status === "scheduled". ⚠️ Function-Form nur im Monolith-Bundle-
-   *  Pattern — siehe Type-Header. */
+  /** Conditional Visibility pro Row. */
   readonly visible?: FieldCondition;
   /** Visual-Style. "danger" rendert rot + erzwingt einen Confirm-
    *  Dialog (auch ohne expliziten `confirm`-Key). */
@@ -177,17 +177,16 @@ export type RowActionNavigate = {
   /** Screen-id (kurz, unqualified) zu dem navigiert wird. Boot-
    *  Validator prüft Existenz im selben Feature. */
   readonly screen: string;
-  /** Optional: Entity-Id für entityEdit-Targets — landet als Pfad-
-   *  Segment (`/<workspace>/<screen>/<entityId>`). entityEdit liest die
-   *  Id AUSSCHLIESSLICH aus dem Pfad; ein `?id=`-Search-Param öffnet
-   *  den Create-Mode. ⚠️ Function-Form nur im Monolith-Bundle-Pattern. */
-  readonly entityId?: (row: Readonly<Record<string, unknown>>) => string;
-  /** Optional: URL-Search-Params aus row-Context. Wird in actionForm-
-   *  Targets als initial values gelesen ("Edit Customer X" → URL hat
-   *  `?customerId=row-uuid`, actionForm initial values pre-fillen).
-   *  ⚠️ Function-Form nur im Monolith-Bundle-Pattern. */
-  readonly params?: (row: Readonly<Record<string, unknown>>) => Record<string, unknown>;
-  /** Conditional Visibility pro Row — analog zu writeHandler-Variante. */
+  /** Feldname dessen Wert als entityId in den URL-Pfad eingebettet wird
+   *  (`/<workspace>/<screen>/<entityId>`). entityEdit liest die Id
+   *  AUSSCHLIESSLICH aus dem Pfad. Default: "id" wenn der Ziel-Screen
+   *  ein entityEdit ist. */
+  readonly entityId?: string;
+  /** Deklarative URL-Search-Params aus row-Context. Wird in actionForm-
+   *  Targets als initial values gelesen (actionForm pre-fillen).
+   *  `pick` extrahiert Felder gleichen Namens; `map` benennt um. */
+  readonly params?: RowFieldExtractor;
+  /** Conditional Visibility pro Row. */
   readonly visible?: FieldCondition;
   readonly style?: "primary" | "secondary";
 };
@@ -195,11 +194,6 @@ export type RowActionNavigate = {
 // ToolbarAction — Button im List-Header. Zwei Varianten: navigate auf
 // einen anderen Screen (z.B. zu einem actionForm) oder direkt einen
 // Handler dispatchen (z.B. "Sync All" ohne Form).
-//
-// ⚠️ Function-Props (`payload`) leben nur im Monolith-Bundle-Pattern
-// (siehe RowAction-JSDoc) — JSON-injected Schemas droppen sie silent.
-// Für solche Apps payload weglassen oder im writeHandler server-side
-// die Tenant-/Session-Kontext-Werte ableiten.
 export type ToolbarAction =
   | {
       readonly kind: "navigate";
@@ -214,8 +208,8 @@ export type ToolbarAction =
       readonly id: string;
       readonly label: string;
       readonly handler: string;
-      /** Optional: Payload-Builder ohne row-Context. Default = `{}`. */
-      readonly payload?: () => Record<string, unknown>;
+      /** Statischer Payload ohne row-Context. Default = `{}`. */
+      readonly payload?: Record<string, unknown>;
       /** i18n-Key für Confirm-Dialog-Description. Wenn gesetzt UND/ODER
        *  style="danger": Modal vor der Ausführung. */
       readonly confirm?: string;

package/src/ui-types/index.ts

@@ -60,6 +60,7 @@ export type {
   RowAction,
   RowActionNavigate,
   RowActionWriteHandler,
+  RowFieldExtractor,
   ScreenDefinition,
   ScreenFilter,
   ScreenFilterOp,