@cosmicdrift/kumiko-framework 0.238.0 → 0.240.0

package/src/engine/registry-validate.ts

@@ -1,6 +1,6 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
 import { resolveName } from "./handler-helpers";
-import type { RegistryState } from "./registry-state";
+import type { RegistryState, SearchableReferenceField } from "./registry-state";
 import { buildImplicitProjection, hasFieldAccessRules, qualify } from "./registry-state";
 import {
   buildSoftDeleteCleanupJob,
@@ -10,7 +10,7 @@ import {
   SOFT_DELETE_GRACE_DAYS_KEY,
   softDeleteGraceDaysConfig,
 } from "./soft-delete-cleanup";
-import type { EventPiiFields, EventUpcastFn, FeatureDefinition } from "./types";
+import type { EventPiiFields, EventUpcastFn, FeatureDefinition, ReferenceFieldDef } from "./types";
 import { HookPhases } from "./types";
 
 function allHandlerQns(state: RegistryState): ReadonlySet<string> {
@@ -154,13 +154,50 @@ export function applyExtensionUsages(state: RegistryState): void {
   }
 }
 
-// Precompute: searchable/sortable fields.
-export function buildSearchableSortableCaches(state: RegistryState): void {
-  // Precompute: searchable/sortable fields, search includes, incoming relations
+// "customer" (same-feature) or "users:customer" (cross-feature,
+// "<featureName>:<entityName>") — only the entity name matters here, names
+// are globally unique in entityMap. Local duplicate of the same parse done
+// in db/eagerload.ts's parseRefEntity — this loop has no feature context to
+// hand to engine/parse-ref-target.ts's parseRefTarget.
+function parseReferenceTargetEntityName(raw: string): string {
+  const idx = raw.indexOf(":");
+  return idx < 0 ? raw : raw.slice(idx + 1);
+}
+
+// fw#2660: labelField defaults to "id" (a UUID column) elsewhere, but a
+// searchable reference ILIKEs the label column — an implicit or explicit
+// "id" default would 500 on every search request. Fail at boot.
+function buildSearchableReferenceField(
+  entityName: string,
+  fieldName: string,
+  field: ReferenceFieldDef,
+): SearchableReferenceField {
+  if (field.labelField === undefined || field.labelField === "id") {
+    throw new Error(
+      `[Entity ${entityName}] field "${fieldName}": searchable reference fields require an ` +
+        `explicit, non-"id" labelField. "id" is a UUID column — ILIKE against it fails ` +
+        `at request time. Set labelField to a human-readable field on the referenced entity.`,
+    );
+  }
+  if (field.multiple === true) {
+    throw new Error(
+      `[Entity ${entityName}] field "${fieldName}": searchable is not supported on multiple ` +
+        `(array) reference fields — remove "multiple" or "searchable".`,
+    );
+  }
+  return {
+    fieldName,
+    targetEntityName: parseReferenceTargetEntityName(field.entity),
+    labelField: field.labelField,
+  };
+}
 
+// Precompute: searchable/sortable fields, searchable reference fields.
+export function buildSearchableSortableCaches(state: RegistryState): void {
   for (const [name, entity] of state.entityMap) {
     const searchable: string[] = [];
     const sortable: string[] = [];
+    const searchableReferences: SearchableReferenceField[] = [];
     for (const [fieldName, field] of Object.entries(entity.fields)) {
       if (field.type === "text" && field.searchable === true) searchable.push(fieldName);
       if (field.type === "text" && field.sortable === true) sortable.push(fieldName);
@@ -169,9 +206,13 @@ export function buildSearchableSortableCaches(state: RegistryState): void {
           if (subField.searchable === true) searchable.push(`${fieldName}_${subName}`);
         }
       }
+      if (field.type === "reference" && field.searchable === true) {
+        searchableReferences.push(buildSearchableReferenceField(name, fieldName, field));
+      }
     }
     state.searchableFieldsCache.set(name, searchable);
     state.sortableFieldsCache.set(name, sortable);
+    state.searchableReferencesCache.set(name, searchableReferences);
   }
 }
 
@@ -223,16 +264,8 @@ export function buildImplicitProjections(
   }
 }
 
-export function buildSearchIncludesAndIncomingRelations(state: RegistryState): void {
+export function buildIncomingRelations(state: RegistryState): void {
   for (const [entityName, rels] of state.relationMap) {
-    const includes = new Map<string, readonly string[]>();
-    for (const [relName, rel] of Object.entries(rels)) {
-      if ((rel.type === "belongsTo" || rel.type === "manyToMany") && rel.searchInclude?.length) {
-        includes.set(relName, rel.searchInclude);
-      }
-    }
-    state.searchIncludesCache.set(entityName, includes);
-
     // Build reverse index for incoming relations
     for (const [relName, rel] of Object.entries(rels)) {
       const existing = state.incomingRelationsCache.get(rel.target) ?? [];

package/src/engine/registry.ts

@@ -20,8 +20,8 @@ import {
   autoWireSoftDeleteJobs,
   buildEventUpcasterChains,
   buildImplicitProjections,
+  buildIncomingRelations,
   buildSearchableSortableCaches,
-  buildSearchIncludesAndIncomingRelations,
   computeHasRateLimitedHandler,
   finalizeWorkspaceNavMembership,
   populateHandlerEntityMappings,
@@ -68,7 +68,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   applyExtensionUsages(state);
   buildSearchableSortableCaches(state);
   buildImplicitProjections(state, features);
-  buildSearchIncludesAndIncomingRelations(state);
+  buildIncomingRelations(state);
   validateFieldAccessHandlersAreEntityMapped(state, features);
   validateExtensionPreSaveWiring(features);
   validateRelationTargetsExist(state);

package/src/engine/screen-helpers.ts

@@ -3,6 +3,7 @@ import type {
   EditFieldSpec,
   EditFieldsSection,
   EditSectionSpec,
+  EditWriteFormSection,
   FieldCondition,
   FormatSpec,
   ListColumnSpec,
@@ -16,6 +17,10 @@ export function isFieldsEditSection(section: EditSectionSpec): section is EditFi
   return section.kind === undefined || section.kind === "fields";
 }
 
+export function isWriteFormEditSection(section: EditSectionSpec): section is EditWriteFormSection {
+  return section.kind === "writeForm";
+}
+
 // Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
 // authors who branch on the three FieldRenderer variants without manual
 // "format" in renderer checks.

package/src/engine/types/index.ts

@@ -275,6 +275,7 @@ export type {
   EditLayout,
   EditRelatedListSection,
   EditSectionSpec,
+  EditWriteFormSection,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FieldCondition,

package/src/i18n/required-surface-keys.ts

@@ -1,4 +1,8 @@
-import { isExtensionEditSection, normalizeListColumn } from "../engine/screen-helpers";
+import {
+  isExtensionEditSection,
+  isWriteFormEditSection,
+  normalizeListColumn,
+} from "../engine/screen-helpers";
 import type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,
@@ -27,6 +31,11 @@ export const CONFIG_EDIT_ENTITY = "__config-edit__";
 /** Pseudo-entity for projectionDetail field labels (renderer projection-detail-shim). */
 export const PROJECTION_DETAIL_ENTITY = "__projection-detail__";
 
+/** Pseudo-entity for a projectionDetail writeForm section's own fieldDefs
+ *  (distinct from PROJECTION_DETAIL_ENTITY — the section's fields aren't
+ *  drawn from the host record's display entity). */
+export const WRITE_FORM_SECTION_ENTITY = "__write-form-section__";
+
 export function fieldLabelKey(featureName: string, entityName: string, fieldName: string): string {
   return `${featureName}:entity:${entityName}:field:${fieldName}`;
 }
@@ -247,6 +256,16 @@ export function requiredKeysFromScreen(
             const normalized = normalizeListColumn(col);
             if (normalized.label !== undefined) pushKey(out, normalized.label);
           }
+          for (const action of section.rowActions ?? []) pushRowActionKeys(out, action);
+          continue;
+        }
+        if (isWriteFormEditSection(section)) {
+          pushKey(out, section.title);
+          pushKey(out, section.submitLabel);
+          for (const f of section.fields) {
+            const fieldName = editFieldName(f);
+            out.add(fieldLabelKey(featureName, WRITE_FORM_SECTION_ENTITY, fieldName));
+          }
           continue;
         }
         pushKey(out, section.title);

package/src/ui-types/index.ts

@@ -30,6 +30,7 @@ export {
   isExtensionEditSection,
   isFieldsEditSection,
   isFormatSpec,
+  isWriteFormEditSection,
   normalizeEditField,
   normalizeListColumn,
 } from "../engine/screen-helpers";
@@ -74,6 +75,7 @@ export type {
   EditLayout,
   EditRelatedListSection,
   EditSectionSpec,
+  EditWriteFormSection,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FieldCondition,
@@ -100,7 +102,10 @@ export type {
 export type { TargetRef } from "../engine/types/target-ref";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node";
 export type { WorkspaceDefinition } from "../engine/types/workspace";
-export { PROJECTION_DETAIL_ENTITY } from "../i18n/required-surface-keys";
+export {
+  PROJECTION_DETAIL_ENTITY,
+  WRITE_FORM_SECTION_ENTITY,
+} from "../i18n/required-surface-keys";
 export type {
   AppSchema,
   FeatureSchema,