@cosmicdrift/kumiko-framework 0.238.0 → 0.240.0

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

@@ -435,6 +435,461 @@ describe("r.screen() — registration", () => {
     );
   });
 
+  test("validateBoot rejects a relatedList rowAction with an unregistered write-handler (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowActions: [{ id: "sync", label: "actions.sync", handler: "app:write:missing" }],
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /relatedList\).*rowAction "sync" handler "app:write:missing".*not a registered write-handler/,
+    );
+  });
+
+  test("validateBoot accepts a relatedList rowAction bound to a registered write-handler (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.writeHandler(
+          "sync",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          {
+            access: { roles: ["Admin"] },
+          },
+        );
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+          access: { openToAll: true },
+        });
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowActions: [
+                  {
+                    id: "sync",
+                    label: "actions.sync",
+                    handler: "app:write:sync",
+                    payload: { pick: ["name"] },
+                  },
+                ],
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("validateBoot rejects a relatedList section with both rowClick and a rowActions rowClick:true entry (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("billing", (r) => {
+        r.entity(
+          "invoice",
+          createEntity({ table: "invoices", fields: { name: createTextField() } }),
+        );
+        r.screen({
+          id: "invoice-detail",
+          type: "custom",
+          renderer: { react: { __component: "stub" } },
+          detailFor: "invoice",
+        });
+      }),
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowClick: { entity: "invoice" },
+                rowActions: [
+                  {
+                    kind: "navigate",
+                    id: "open",
+                    label: "actions.open",
+                    entity: "invoice",
+                    entityId: "id",
+                    rowClick: true,
+                  },
+                ],
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /relatedList\).*has both a rowClick and 1 rowActions marked rowClick:true/,
+    );
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section with an empty fieldDefs map (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: {},
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/\(writeForm\) has an empty fieldDefs map/);
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section with zero fields (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: [],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/\(writeForm\) has zero fields/);
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm field with no entry in fieldDefs (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["sku"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(writeForm\) field "sku" has no entry in fieldDefs/,
+    );
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section in a wizard layout (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            mode: "wizard",
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/writeForm.*wizard layout/);
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section with an unregistered write-handler (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:missing",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(writeForm\) handler "app:write:missing".*not a registered write-handler/,
+    );
+  });
+
+  test("validateBoot accepts a valid projectionDetail writeForm section (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.writeHandler(
+          "save",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          {
+            access: { roles: ["Admin"] },
+          },
+        );
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+                submitLabel: "actions.save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  // withBootValidatorFixture auto-fills every key requiredKeysFromFeature
+  // reports, so every other boot test in this file passes regardless of
+  // whether required-surface-keys.ts's writeForm branch names the right key
+  // — it would pass even for a wrong namespace. Bypass the fixture (raw
+  // validateBootRaw, no stubTranslations) to pin the actual key contract.
+  test("validateBoot requires a translation for a writeForm field's own label, namespaced under the write-form pseudo-entity (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        // Screens always require their own "screen:<id>.title" key — supplied
+        // here so the throw below isolates the one key this test is about.
+        r.translations({ keys: { "screen:x.title": { en: "X" } } });
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.writeHandler(
+          "save",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+
+    expect(() => validateBootRaw(features)).toThrow(
+      '[i18n] Feature "app": required translation key missing: "app:entity:__write-form-section__:field:name"',
+    );
+  });
+
+  test("translating the writeForm field's pseudo-entity key lets boot pass", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.translations({
+          keys: {
+            "screen:x.title": { en: "X" },
+            "app:entity:__write-form-section__:field:name": { en: "Name" },
+          },
+        });
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.writeHandler(
+          "save",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+
+    expect(() => validateBootRaw(features)).not.toThrow();
+  });
+
+  test("validateBoot rejects a writeForm section on entityEdit (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.entity("product", productEntity());
+        r.screen({
+          id: "product-edit",
+          type: "entityEdit",
+          entity: "product",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "shop:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(entityEdit\) writeForm section "s".*projectionDetail-only/,
+    );
+  });
+
+  test("validateBoot rejects a writeForm section on configEdit (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.config({
+          keys: { "site-name": createTenantConfig("text", { default: "" }) },
+        });
+        r.screen({
+          id: "settings",
+          type: "configEdit",
+          scope: "tenant",
+          configKeys: { siteName: "shop:config:site-name" },
+          fields: { siteName: { type: "text" } } as never,
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "shop:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(configEdit\) writeForm section "s".*projectionDetail-only/,
+    );
+  });
+
+  test("validateBoot rejects a writeForm section on actionForm (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.writeHandler(
+          "restock",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "restock",
+          type: "actionForm",
+          handler: "shop:write:restock",
+          fields: { qty: { type: "number" } } as never,
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "shop:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(actionForm\) writeForm section "s".*projectionDetail-only/,
+    );
+  });
+
   test("stores an entityEdit screen with sections + conditional fields", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", productEntity());

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

@@ -9,7 +9,12 @@ import { rowMetaFieldNames } from "../../db/table-builder";
 import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta";
 import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
-import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
+import {
+  isExtensionEditSection,
+  isWriteFormEditSection,
+  normalizeEditField,
+  normalizeListColumn,
+} from "../screen-helpers";
 import type { EntityDefinition, FeatureDefinition } from "../types";
 import type {
   DashboardCustomPanel,
@@ -732,6 +737,93 @@ export function validateScreens(
               );
             }
           }
+          if (section.rowActions !== undefined) {
+            for (const action of section.rowActions) {
+              if (action.kind === "navigate") {
+                const target = resolveRowActionNavigateTarget(
+                  feature.name,
+                  screenId,
+                  "projectionDetail",
+                  "rowAction",
+                  action,
+                  allScreenQns,
+                  navTargetShortIds,
+                  screensByShortId,
+                  detailForScreens,
+                );
+                validateRowActionNavigateParams(
+                  feature.name,
+                  screenId,
+                  "projectionDetail",
+                  undefined,
+                  action,
+                  target,
+                );
+              } else if (!allWriteHandlerQns.has(action.handler)) {
+                throw new Error(
+                  `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section ` +
+                    `"${section.title}" (relatedList) 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(...).`,
+                );
+              }
+            }
+            // section.rowClick (legacy, navigate-only) and a rowActions entry
+            // marked rowClick:true both claim the row-body click — same
+            // at-most-one constraint as entityList/projectionList's
+            // validateAtMostOneRowClick, just spanning two fields instead of one.
+            const rowClickActionCount = section.rowActions.filter(
+              (a) => a.kind === "navigate" && a.rowClick === true,
+            ).length;
+            const legacyRowClickCount = section.rowClick !== undefined ? 1 : 0;
+            if (rowClickActionCount + legacyRowClickCount > 1) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                  `(relatedList) has both a rowClick and ${rowClickActionCount} rowActions marked ` +
+                  `rowClick:true — at most one may fire on a row-body click.`,
+              );
+            }
+          }
+          continue;
+        }
+        if (isWriteFormEditSection(section)) {
+          if (Object.keys(section.fieldDefs).length === 0) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(writeForm) has an empty fieldDefs map — declare at least one field type.`,
+            );
+          }
+          if (section.fields.length === 0) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(writeForm) has zero fields — drop the section or add fields to it.`,
+            );
+          }
+          for (const f of section.fields) {
+            const fieldName = normalizeEditField(f).field;
+            if (section.fieldDefs[fieldName] === undefined) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                  `(writeForm) field "${fieldName}" has no entry in fieldDefs — every rendered field needs ` +
+                  `a type declared there.`,
+              );
+            }
+          }
+          if (screen.layout.mode === "wizard") {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `is kind "writeForm" in a wizard layout — a self-persisting form is not supported in a ` +
+                `stepped form. Remove mode: "wizard" or drop the writeForm section.`,
+            );
+          }
+          if (!allWriteHandlerQns.has(section.handler)) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(writeForm) handler "${section.handler}" is not a registered write-handler. Check the QN ` +
+                `spelling (expected "<feature>:write:<short>") and that the handler is declared via ` +
+                `r.writeHandler(...).`,
+            );
+          }
           continue;
         }
         if (section.fields.length === 0) {
@@ -837,6 +929,12 @@ export function validateScreens(
               `primitive (fw#2166).`,
           );
         }
+        if (isWriteFormEditSection(section)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (configEdit) writeForm section ` +
+              `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (configEdit) has a section "${section.title}" ` +
@@ -952,6 +1050,12 @@ export function validateScreens(
               `primitive (fw#2166).`,
           );
         }
+        if (isWriteFormEditSection(section)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) writeForm section ` +
+              `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has a section "${section.title}" ` +
@@ -1308,6 +1412,12 @@ export function validateScreens(
               `primitive (fw#2166).`,
           );
         }
+        if (isWriteFormEditSection(section)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) writeForm section ` +
+              `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) has a section "${section.title}" ` +

package/src/engine/entity-handlers.ts

@@ -339,6 +339,13 @@ export function defineEntityQueryHandler(
         const result = await executor.list(listPayload, query.user, db, {
           ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
           ...(ctx.includeDeleted === true && { includeDeleted: true }),
+          // fw#2660 — registry access only exists at request time, so the
+          // searchable-reference cache + entity resolver travel through the
+          // same runtime-override extension point as searchAdapter above.
+          referenceSearch: {
+            fields: ctx.registry.getSearchableReferences(entityName),
+            resolveEntity: (name) => ctx.registry.getEntity(name),
+          },
         });
         const enrichedRows = hasRefFields
           ? await enrichWithReferences(

package/src/engine/index.ts

@@ -242,6 +242,7 @@ export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-build
 export {
   isExtensionEditSection,
   isFieldsEditSection,
+  isWriteFormEditSection,
   normalizeEditField,
   normalizeListColumn,
 } from "./screen-helpers";

package/src/engine/registry-facade.ts

@@ -1,4 +1,4 @@
-import type { IncomingRelation, RegistryState } from "./registry-state";
+import type { IncomingRelation, RegistryState, SearchableReferenceField } from "./registry-state";
 import { filterByPhase, filterOwned } from "./registry-state";
 import type {
   AuthClaimsHookDef,
@@ -97,8 +97,8 @@ export function buildRegistryFacade(state: RegistryState): Registry {
       return (state.relationMap.get(entityName) ?? {}) as EntityRelations; // @cast-boundary schema-walk
     },
 
-    getSearchIncludes(entityName: string): ReadonlyMap<string, readonly string[]> {
-      return state.searchIncludesCache.get(entityName) ?? new Map();
+    getSearchableReferences(entityName: string): readonly SearchableReferenceField[] {
+      return state.searchableReferencesCache.get(entityName) ?? [];
     },
 
     getIncomingRelations(entityName: string): readonly IncomingRelation[] {

package/src/engine/registry-state.ts

@@ -49,6 +49,17 @@ export type IncomingRelation = {
   relation: RelationDefinition;
 };
 
+// One entry per `ReferenceFieldDef` with `searchable: true` (fw#2660) —
+// resolved once at boot so the read-path never re-parses `field.entity`
+// per request. `labelField` is guaranteed defined here: buildSearchableSortableCaches
+// throws at boot for a searchable reference missing an explicit labelField
+// (the "id" default is a UUID column, ILIKE against it would 500 at request time).
+export type SearchableReferenceField = {
+  readonly fieldName: string;
+  readonly targetEntityName: string;
+  readonly labelField: string;
+};
+
 const IMPLICIT_PROJECTION_SUFFIX = "-entity" as const;
 
 // Pro r.entity-Registration eine ImplicitProjection mit auto-generierten
@@ -223,7 +234,7 @@ export type RegistryState = {
   treeActionsMap: Map<string, Readonly<Record<string, TreeActionDef>>>;
   searchableFieldsCache: Map<string, readonly string[]>;
   sortableFieldsCache: Map<string, readonly string[]>;
-  searchIncludesCache: Map<string, ReadonlyMap<string, readonly string[]>>;
+  searchableReferencesCache: Map<string, readonly SearchableReferenceField[]>;
   incomingRelationsCache: Map<string, IncomingRelation[]>;
   hasRateLimitedHandlerCached: boolean;
 };
@@ -286,7 +297,7 @@ export function createInitialState(): RegistryState {
     treeActionsMap: new Map(),
     searchableFieldsCache: new Map(),
     sortableFieldsCache: new Map(),
-    searchIncludesCache: new Map(),
+    searchableReferencesCache: new Map(),
     incomingRelationsCache: new Map(),
     hasRateLimitedHandlerCached: false,
   };