@cosmicdrift/kumiko-framework 0.201.0 → 0.203.0

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

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+describe("validateBoot — detailFor screens (fw#2163)", () => {
+  test("two screens with the same detailFor fail boot, naming both screen ids", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.screen({
+        id: "item-detail-a",
+        type: "custom",
+        renderer: { react: "stub" },
+        detailFor: "item",
+      });
+      r.screen({
+        id: "item-detail-b",
+        type: "custom",
+        renderer: { react: "stub" },
+        detailFor: "item",
+      });
+      r.translations({
+        keys: {
+          "screen:item-detail-a.title": { de: "A", en: "A" },
+          "screen:item-detail-b.title": { de: "B", en: "B" },
+          "demo:entity:item:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/detailFor: "item"/);
+    expect(() => validateBoot([feature])).toThrow(/demo:screen:item-detail-a/);
+    expect(() => validateBoot([feature])).toThrow(/demo:screen:item-detail-b/);
+  });
+
+  test("detailFor on an unknown entity fails boot", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.screen({
+        id: "item-detail",
+        type: "custom",
+        renderer: { react: "stub" },
+        detailFor: "ghost",
+      });
+      r.translations({
+        keys: {
+          "screen:item-detail.title": { de: "Detail", en: "Detail" },
+          "demo:entity:item:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/"ghost"/);
+  });
+
+  test("a valid detailFor on a custom screen passes boot", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.screen({
+        id: "item-detail",
+        type: "custom",
+        renderer: { react: "stub" },
+        detailFor: "item",
+      });
+      r.translations({
+        keys: {
+          "screen:item-detail.title": { de: "Detail", en: "Detail" },
+          "demo:entity:item:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("an entity without any detail screen passes boot", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.translations({
+        keys: { "demo:entity:item:field:name": { de: "Name", en: "Name" } },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});

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

@@ -0,0 +1,191 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+
+describe("validateBoot — projectionList screens", () => {
+  test("rejects hand-written searchable:true when the query schema has no search param (3a)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: true,
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/searchable: true.*"search"/);
+  });
+
+  test("requires defaultSort when the query schema accepts search (3b)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({ search: z.string().optional() }),
+        async () => ({ rows: [], nextCursor: null }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/defaultSort required/);
+  });
+
+  test("requires defaultSort when the query schema accepts sort (3b)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({ sort: z.string().optional() }),
+        async () => ({ rows: [], nextCursor: null }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/defaultSort required/);
+  });
+
+  test("passes when search/sort are active and defaultSort is set", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({ search: z.string().optional(), sort: z.string().optional() }),
+        async () => ({ rows: [], nextCursor: null }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: true,
+        defaultSort: { field: "description", dir: "asc" },
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("passes when the schema offers neither search nor sort and no defaultSort is set", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("rejects hand-written searchable:false when the query schema accepts search and the screen isn't whitelisted", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({ search: z.string().optional() }),
+        async () => ({ rows: [], nextCursor: null }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: false,
+        defaultSort: { field: "description", dir: "asc" },
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/searchable: false disables it/);
+  });
+
+  test("passes hand-written searchable:false on a whitelisted screen id even when the schema accepts search", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({ search: z.string().optional() }),
+        async () => ({ rows: [], nextCursor: null }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "download-attempt-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: false,
+      });
+      r.translations({
+        keys: { "screen:download-attempt-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("rejects hand-authored sortable on a projectionList screen (fw#2165 review)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        sortable: true,
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/sortable is derived/);
+  });
+
+  test("rejects hand-authored paginated on a projectionList screen (fw#2165 review)", () => {
+    const feature = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        paginated: false,
+      });
+      r.translations({
+        keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/paginated is derived/);
+  });
+});

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

@@ -8,10 +8,12 @@
 //      im Browser-Bundle.
 
 import { describe, expect, test } from "bun:test";
+import { z } from "zod";
 import { buildAppSchema, findNonJsonSafePath } from "../build-app-schema";
 import { defineFeature } from "../define-feature";
 import { createRegistry } from "../registry";
 import type { EntityDefinition } from "../types/fields";
+import type { ProjectionListScreenDefinition } from "../types/screen";
 
 describe("buildAppSchema", () => {
   test("Multi-Feature: jedes Feature wird mit eigenem featureName projiziert", () => {
@@ -91,6 +93,31 @@ describe("buildAppSchema", () => {
     expect(screen).toMatchObject({ id: "privacy-center", dormant: true });
   });
 
+  // fw#2163: resolveTarget (renderer) reads screen.detailFor + screen.id
+  // (short, unqualified) off the client FeatureSchema — this pins that both
+  // survive the server→client projection verbatim, on a real registry-built
+  // schema rather than a hand-rolled FeatureSchema literal.
+  test("custom screen's `detailFor` survives the buildAppSchema projection, screen id stays unqualified (#2163)", () => {
+    const propertyFeature = defineFeature("property", (r) => {
+      r.entity("lease", {
+        table: "leases",
+        fields: { name: { type: "text" } },
+      } as unknown as EntityDefinition);
+      r.screen({
+        id: "lease-detail",
+        type: "custom",
+        renderer: { react: { __component: "LeaseDetailScreen" } },
+        detailFor: "lease",
+      });
+      r.translations({ keys: { "screen:lease-detail.title": { de: "Detail", en: "Detail" } } });
+    });
+
+    const app = buildAppSchema(createRegistry([propertyFeature]));
+    const screen = app.features.find((f) => f.featureName === "property")?.screens[0];
+
+    expect(screen).toMatchObject({ id: "lease-detail", detailFor: "lease" });
+  });
+
   test("Feature ohne r.translations lässt das Feld weg (omit-undefined-Pattern)", () => {
     const f = defineFeature("bare", (r) => {
       r.nav({ id: "x", label: "X" });
@@ -430,6 +457,98 @@ describe("buildAppSchema", () => {
     expect(entity?.derivedFields?.["phase"]).not.toHaveProperty("derive");
     expect(findNonJsonSafePath(app, "schema")).toBeNull();
   });
+
+  // fw#2165: projectionList's searchable/sortable/paginated are derived from
+  // the bound query handler's Zod schema, not authored — see
+  // deriveProjectionListCapabilities in build-app-schema.ts.
+  test("projectionList: search/sort/cursor in the query schema become derived capabilities (fw#2165)", () => {
+    const f = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.object({
+          search: z.string().optional(),
+          sort: z.string().optional(),
+          cursor: z.string().optional(),
+        }),
+        async () => ({ rows: [], nextCursor: null }),
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+    });
+
+    const app = buildAppSchema(createRegistry([f]));
+    const screen = app.features[0]?.screens[0] as ProjectionListScreenDefinition;
+    expect(screen.searchable).toBe(true);
+    expect(screen.sortable).toBe(true);
+    expect(screen.paginated).toBe(true);
+  });
+
+  test("projectionList: a query schema without search/sort/cursor derives no capability", () => {
+    const f = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({}), async () => ({ rows: [], nextCursor: null }));
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+    });
+
+    const app = buildAppSchema(createRegistry([f]));
+    const screen = app.features[0]?.screens[0] as ProjectionListScreenDefinition;
+    expect(screen.searchable).toBe(false);
+    expect(screen.sortable).toBe(false);
+    expect(screen.paginated).toBe(false);
+  });
+
+  test("projectionList: a non-ZodObject query schema (z.union) derives no capability and doesn't throw", () => {
+    const f = defineFeature("ledger", (r) => {
+      r.queryHandler(
+        "schedule:list",
+        z.union([z.object({ a: z.string() }), z.object({ b: z.string() })]),
+        async () => ({ rows: [], nextCursor: null }),
+      );
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+      });
+    });
+
+    let app: ReturnType<typeof buildAppSchema> | undefined;
+    expect(() => {
+      app = buildAppSchema(createRegistry([f]));
+    }).not.toThrow();
+    const screen = app?.features[0]?.screens[0] as ProjectionListScreenDefinition;
+    expect(screen.searchable).toBe(false);
+    expect(screen.sortable).toBe(false);
+    expect(screen.paginated).toBe(false);
+  });
+
+  test("projectionList: author-written searchable:false survives even when the schema accepts search", () => {
+    const f = defineFeature("ledger", (r) => {
+      r.queryHandler("schedule:list", z.object({ search: z.string().optional() }), async () => ({
+        rows: [],
+        nextCursor: null,
+      }));
+      r.screen({
+        id: "schedule-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: ["description"],
+        searchable: false,
+      });
+    });
+
+    const app = buildAppSchema(createRegistry([f]));
+    const screen = app.features[0]?.screens[0] as ProjectionListScreenDefinition;
+    expect(screen.searchable).toBe(false);
+  });
 });
 
 describe("findNonJsonSafePath", () => {

package/src/engine/__tests__/projection-detail-actions.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+// fw#2166: projectionDetail screens can declare header `actions`, reusing
+// RowAction (the displayed record stands in for the row). `rowClick` has no
+// row to target on a detail screen and is rejected outright; navigate/
+// writeHandler actions get the same existence checks as entityList/
+// projectionList rowActions/toolbarActions.
+describe("validateBoot — projectionDetail actions (fw#2166)", () => {
+  test("navigate action with rowClick: true throws, naming the screen and action", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [
+          {
+            kind: "navigate",
+            id: "edit",
+            label: "actions.edit",
+            screen: "rent-edit",
+            rowClick: true,
+          },
+        ],
+      });
+      r.screen({ id: "rent-edit", type: "custom", renderer: { react: "stub" } });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /Screen "app:screen:rent-detail" \(projectionDetail\) action "edit" sets rowClick: true/,
+    );
+  });
+
+  test("valid navigate + writeHandler actions boot cleanly", () => {
+    const feature = defineFeature("app", (r) => {
+      r.writeHandler(
+        "archive",
+        z.object({ id: z.string() }),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { openToAll: true } },
+      );
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [
+          { kind: "navigate", id: "edit", label: "actions.edit", screen: "rent-edit" },
+          {
+            kind: "writeHandler",
+            id: "archive",
+            label: "actions.archive",
+            handler: "app:write:archive",
+          },
+        ],
+      });
+      r.screen({ id: "rent-edit", type: "custom", renderer: { react: "stub" } });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("navigate action to an unregistered screen throws, via the same existence check as entityList/projectionList", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [{ kind: "navigate", id: "edit", label: "actions.edit", screen: "ghost-screen" }],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /action "edit" navigate-target "ghost-screen" does not resolve to a registered screen/,
+    );
+  });
+
+  test("navigate action with params targeting an entityEdit of the SAME entity (via detailFor) throws — params are a no-op on an update target (review finding 3b)", () => {
+    const feature = defineFeature("app", (r) => {
+      r.entity("rent", createEntity({ fields: { name: createTextField() } }));
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        detailFor: "rent",
+        actions: [
+          {
+            kind: "navigate",
+            id: "edit",
+            label: "actions.edit",
+            screen: "rent-edit",
+            params: { pick: ["name"] },
+          },
+        ],
+      });
+      r.screen({
+        id: "rent-edit",
+        type: "entityEdit",
+        entity: "rent",
+        layout: { sections: [{ columns: 1, fields: ["name"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /rowAction "edit" sets params on navigate-target "rent-edit" which resolves to UPDATE mode \(same entity "rent" auto-fills row\["id"\]\)/,
+    );
+  });
+
+  test("writeHandler action referencing an unregistered handler QN throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-detail",
+        type: "projectionDetail",
+        query: "app:query:rent:detail",
+        layout: { sections: [{ title: "s", fields: ["description"] }] },
+        actions: [
+          {
+            kind: "writeHandler",
+            id: "archive",
+            label: "actions.archive",
+            handler: "app:write:ghost",
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /action "archive" handler "app:write:ghost" is not a registered write-handler/,
+    );
+  });
+});

package/src/engine/boot-validator/action-wiring.ts

@@ -29,7 +29,7 @@ const ACTION_FUNCTION_FIELDS = ["payload", "params", "entityId", "visible"] as c
 function validateActionNoFunctions(
   featureName: string,
   screenId: string,
-  actionKind: "rowAction" | "toolbarAction",
+  actionKind: "rowAction" | "toolbarAction" | "action",
   action: RowAction | ToolbarAction,
 ): void {
   const record = action as unknown as Record<string, unknown>;
@@ -45,6 +45,12 @@ function validateActionNoFunctions(
 
 export function validateActionWiring(feature: FeatureDefinition): void {
   for (const screen of Object.values(feature.screens)) {
+    if (screen.type === "projectionDetail") {
+      for (const action of screen.actions ?? []) {
+        validateActionNoFunctions(feature.name, screen.id, "action", action);
+      }
+      continue;
+    }
     if (screen.type !== "entityList" && screen.type !== "projectionList") continue;
     for (const action of screen.rowActions ?? []) {
       validateActionNoFunctions(feature.name, screen.id, "rowAction", action);

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

@@ -0,0 +1,35 @@
+import { qualifyEntityName } from "../qualified-name";
+import type { FeatureDefinition } from "../types";
+import { findEntityFeature } from "./screens";
+
+export function validateDetailForScreens(
+  features: readonly FeatureDefinition[],
+  featureMap: ReadonlyMap<string, FeatureDefinition>,
+): void {
+  const screenQnByEntity = new Map<string, string>();
+
+  for (const feature of features) {
+    for (const [screenId, screen] of Object.entries(feature.screens)) {
+      const detailFor = screen.detailFor;
+      if (detailFor === undefined) continue;
+
+      const qualified = qualifyEntityName(feature.name, "screen", screenId);
+
+      const existingQn = screenQnByEntity.get(detailFor);
+      if (existingQn !== undefined) {
+        throw new Error(
+          `[detailFor] Screens "${existingQn}" and "${qualified}" both declare ` +
+            `detailFor: "${detailFor}" — only one screen may be the detail view for an entity.`,
+        );
+      }
+      screenQnByEntity.set(detailFor, qualified);
+
+      if (findEntityFeature(detailFor, featureMap) === undefined) {
+        throw new Error(
+          `[detailFor] Screen "${qualified}" declares detailFor: "${detailFor}", ` +
+            `but no feature registers an entity with that name.`,
+        );
+      }
+    }
+  }
+}

package/src/engine/boot-validator/index.ts

@@ -16,6 +16,7 @@ import {
   validateConfigReads,
   warnOnToggleableDependencies,
 } from "./config-deps";
+import { validateDetailForScreens } from "./detail-screens";
 import {
   validateDerivedFieldCollisions,
   validateEmbeddedFields,
@@ -44,6 +45,7 @@ import {
 } from "./nav";
 import { validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
+import { validateProjectionListScreens } from "./projection-list-screens";
 import {
   collectScreenQns,
   collectScreensByShortId,
@@ -208,6 +210,8 @@ export function validateBoot(
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
   validateI18nSurfaceKeys(features);
   validateEntityListScreens(features);
+  validateDetailForScreens(features, featureMap);
+  validateProjectionListScreens(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
   validateFeatureBootChecks(features);