@cosmicdrift/kumiko-framework 0.188.0 → 0.190.0

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

@@ -7,8 +7,11 @@ import { validateBoot as validateBootRaw } from "../boot-validator";
 import { createSystemConfig, createTenantConfig } from "../config-helpers";
 import {
   createDerivedField,
+  createEmbeddedField,
   createEmbeddedListField,
   createEntity,
+  createFilesField,
+  createJsonbField,
   createMultiSelectField,
   createTextField,
   defineFeature,
@@ -1864,6 +1867,39 @@ describe("boot-validator", () => {
       expect(() => validateBoot([makeFeature({ cancelTarget: false })])).not.toThrow();
     });
 
+    // --- redirect/cancelTarget: cross-feature QN (#1946) ---
+    test("redirect → voll-qualifizierte Cross-Feature-QN → kein Throw", () => {
+      const consumer = defineFeature("statements", (r) => {
+        r.screen({ id: "statement-upload-list", type: "custom", renderer: { react: "stub" } });
+      });
+      expect(() =>
+        validateBoot([
+          makeFeature({ redirect: "statements:screen:statement-upload-list" }),
+          consumer,
+        ]),
+      ).not.toThrow();
+    });
+
+    test("redirect → unbekannte Cross-Feature-QN → Throw", () => {
+      expect(() =>
+        validateBoot([makeFeature({ redirect: "statements:screen:ghost-screen" })]),
+      ).toThrow(
+        /redirect "statements:screen:ghost-screen" does not resolve to a registered screen/,
+      );
+    });
+
+    test("cancelTarget → voll-qualifizierte Cross-Feature-QN → kein Throw", () => {
+      const consumer = defineFeature("statements", (r) => {
+        r.screen({ id: "statement-upload-list", type: "custom", renderer: { react: "stub" } });
+      });
+      expect(() =>
+        validateBoot([
+          makeFeature({ cancelTarget: "statements:screen:statement-upload-list" }),
+          consumer,
+        ]),
+      ).not.toThrow();
+    });
+
     test("extension section ohne component → Throw (Parität zu entityEdit)", () => {
       // synthesizeActionFormScreen reicht die layout 1:1 an RenderEdit weiter —
       // eine Extension-Section ohne react/native-Marker rendert sonst stumm leer.
@@ -2173,6 +2209,247 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- entityEdit redirect (framework#1942) ---
+  // Post-save navigation target, same validation as actionForm's redirect:
+  // short screen-ID, same feature, must resolve to a registered screen.
+  describe("entityEdit redirect", () => {
+    function makeFeature(redirect?: string, extraScreens: readonly string[] = []) {
+      return defineFeature("shop", (r) => {
+        r.entity(
+          "product",
+          createEntity({ fields: { name: createTextField(), sku: createTextField() } }),
+        );
+        r.screen({
+          id: "product-edit",
+          type: "entityEdit",
+          entity: "product",
+          layout: { sections: [{ fields: ["name", "sku"] }] },
+          ...(redirect !== undefined && { redirect }),
+        });
+        for (const extra of extraScreens) {
+          r.screen({
+            id: extra,
+            type: "custom",
+            renderer: { react: "stub" },
+          });
+        }
+      });
+    }
+
+    test("redirect → existing screen-id im selben feature → kein Throw", () => {
+      expect(() => validateBoot([makeFeature("product-list", ["product-list"])])).not.toThrow();
+    });
+
+    test("redirect → unknown screen-id → Throw", () => {
+      expect(() => validateBoot([makeFeature("ghost-screen")])).toThrow(
+        /redirect "ghost-screen" does not resolve to a registered screen/,
+      );
+    });
+
+    test("kein redirect gesetzt → kein Throw (Default: Liste)", () => {
+      expect(() => validateBoot([makeFeature()])).not.toThrow();
+    });
+
+    // --- redirect: cross-feature QN (#1946) ---
+    test("redirect → voll-qualifizierte Cross-Feature-QN → kein Throw", () => {
+      const consumer = defineFeature("statements", (r) => {
+        r.screen({ id: "statement-upload-list", type: "custom", renderer: { react: "stub" } });
+      });
+      expect(() =>
+        validateBoot([makeFeature("statements:screen:statement-upload-list"), consumer]),
+      ).not.toThrow();
+    });
+
+    test("redirect → unbekannte Cross-Feature-QN → Throw", () => {
+      expect(() => validateBoot([makeFeature("statements:screen:ghost-screen")])).toThrow(
+        /redirect "statements:screen:ghost-screen" does not resolve to a registered screen/,
+      );
+    });
+  });
+
+  // --- no-widget field types + required (#1925) ---
+  // jsonb/embedded/files/images render read-only on the auto-wired
+  // entityEdit path (render-field.tsx) — a statically-`required: true`
+  // field of one of these types would be unresolvable by the user, so it's
+  // caught loudly at boot instead of silently accepting an unfillable form.
+  // Only the static case (literal `true`, entity-level or screen-spec) is
+  // checked; a dynamic FieldCondition can't be evaluated without runtime
+  // form values and is a documented, accepted gap.
+  describe("no-widget field types + required (#1925)", () => {
+    test("embedded field, entity-level required: true → Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "order",
+            createEntity({
+              fields: {
+                lines: createEmbeddedField({ note: { type: "text" } }, { required: true }),
+              },
+            }),
+          );
+          r.screen({
+            id: "order-edit",
+            type: "entityEdit",
+            entity: "order",
+            layout: { sections: [{ fields: ["lines"] }] },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /field "lines" is type "embedded", which renders read-only/,
+      );
+    });
+
+    test("embedded field, entity-level required: true, screen-spec required: false override → kein Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "order",
+            createEntity({
+              fields: {
+                lines: createEmbeddedField({ note: { type: "text" } }, { required: true }),
+              },
+            }),
+          );
+          r.screen({
+            id: "order-edit",
+            type: "entityEdit",
+            entity: "order",
+            layout: { sections: [{ fields: [{ field: "lines", required: false }] }] },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+
+    test("embedded field, entity-level required: true, screen-spec readOnly: true → kein Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "order",
+            createEntity({
+              fields: {
+                lines: createEmbeddedField({ note: { type: "text" } }, { required: true }),
+              },
+            }),
+          );
+          r.screen({
+            id: "order-edit",
+            type: "entityEdit",
+            entity: "order",
+            layout: { sections: [{ fields: [{ field: "lines", readOnly: true }] }] },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+
+    test("embedded field, entity-level required: true, dynamic screen-spec required condition → kein Throw (not statically resolvable)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "order",
+            createEntity({
+              fields: {
+                kind: createTextField(),
+                lines: createEmbeddedField({ note: { type: "text" } }, { required: true }),
+              },
+            }),
+          );
+          r.screen({
+            id: "order-edit",
+            type: "entityEdit",
+            entity: "order",
+            layout: {
+              sections: [
+                { fields: ["kind", { field: "lines", required: { field: "kind", eq: "b2b" } }] },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+
+    test("jsonb field, screen-spec required: true override → Throw (JsonbFieldDef has no entity-level required)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity("order", createEntity({ fields: { data: createJsonbField() } }));
+          r.screen({
+            id: "order-edit",
+            type: "entityEdit",
+            entity: "order",
+            layout: { sections: [{ fields: [{ field: "data", required: true }] }] },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /field "data" is type "jsonb", which renders read-only/,
+      );
+    });
+
+    test("files field, screen-spec required: true override → Throw (deliberately deferred, no multi-upload widget)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity("order", createEntity({ fields: { attachments: createFilesField() } }));
+          r.screen({
+            id: "order-edit",
+            type: "entityEdit",
+            entity: "order",
+            layout: { sections: [{ fields: [{ field: "attachments", required: true }] }] },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /field "attachments" is type "files", which renders read-only/,
+      );
+    });
+
+    test("multiSelect field, entity-level required: true → kein Throw (has a combobox widget since #1925)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "product",
+            createEntity({
+              fields: {
+                tags: createMultiSelectField({ options: ["a", "b"] as const, required: true }),
+              },
+            }),
+          );
+          r.screen({
+            id: "product-edit",
+            type: "entityEdit",
+            entity: "product",
+            layout: { sections: [{ fields: ["tags"] }] },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+
+    test("embedded LIST field (multiple: true), entity-level required: true → kein Throw (has an EmbeddedListField grid widget since #1838)", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.entity(
+            "invoice",
+            createEntity({
+              fields: {
+                lines: createEmbeddedListField({ note: { type: "text" } }, { required: true }),
+              },
+            }),
+          );
+          r.screen({
+            id: "invoice-edit",
+            type: "entityEdit",
+            entity: "invoice",
+            layout: { sections: [{ fields: ["lines"] }] },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+  });
+
   // --- Tier 2.7e-3: ReferenceFieldDef ---
   describe("reference field (Tier 2.7e-3)", () => {
     test("reference auf bestehende Entity → kein Throw", () => {

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

@@ -5,16 +5,17 @@
 // same-folder require cycle.
 
 import { rowMetaFieldNames } from "../../db/table-builder";
-import { qualifyEntityName } from "../qualified-name";
+import { isValidQn, qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
-import type { FeatureDefinition } from "../types";
+import type { EntityDefinition, FeatureDefinition } from "../types";
 import type {
   DashboardCustomPanel,
   DashboardFilterDefinition,
   DashboardPanelDefinition,
   DashboardScreenDefinition,
   DashboardStatGroupPanel,
+  EditFieldSpec,
   EditLayout,
   FieldCondition,
   RowAction,
@@ -23,6 +24,48 @@ import type {
   ToolbarAction,
 } from "../types/screen";
 
+// Mirrors FIELD_TYPES_WITHOUT_WIDGET in packages/renderer/src/app/form-schema.ts.
+// Can't import it directly — renderer depends on framework, not the reverse.
+// Keep both lists in sync when a field type gains or loses an auto-wired widget.
+const NO_WIDGET_FIELD_TYPES = new Set(["jsonb", "embedded", "files", "images"]);
+
+// A field type in NO_WIDGET_FIELD_TYPES renders read-only on the auto-wired
+// entityEdit path (#1925) — a required field the user can never fill would
+// block every save. Only the statically-resolvable case is caught here: a
+// literal `required: true` (screen-spec override or entity-level default).
+// A dynamic FieldCondition depends on runtime form values and can't be
+// evaluated at boot; buildFormSchema() silently skips presence-checking it.
+function validateNoWidgetRequiredField(
+  featureName: string,
+  screenId: string,
+  entityDef: EntityDefinition,
+  fieldSpec: Exclude<EditFieldSpec, string>,
+): void {
+  const fieldDef = entityDef.fields[fieldSpec.field];
+  // skip: field doesn't exist or its type already has a widget — nothing to validate.
+  if (fieldDef === undefined || !NO_WIDGET_FIELD_TYPES.has(fieldDef.type)) return;
+  // Embedded LIST fields (`multiple: true`) get their own EmbeddedListField
+  // grid widget (#1838) — only plain (non-list) embedded has no widget.
+  const isEmbeddedList =
+    fieldDef.type === "embedded" &&
+    (fieldDef as unknown as { multiple?: boolean }).multiple === true;
+  // skip: list variant has a widget — not the no-widget case this guard targets.
+  if (isEmbeddedList) return;
+  // skip: already read-only by spec — no fillable widget needed regardless of type.
+  if (fieldSpec.readOnly === true) return;
+  const entityRequired = "required" in fieldDef && fieldDef.required === true;
+  const isStaticallyRequired =
+    fieldSpec.required === undefined ? entityRequired : fieldSpec.required === true;
+  // skip: not required — a read-only widget-less field is fine to leave empty.
+  if (!isStaticallyRequired) return;
+  throw new Error(
+    `[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${fieldSpec.field}" is ` +
+      `type "${fieldDef.type}", which renders read-only on the auto-wired entityEdit path — a ` +
+      `required field the user could never fill would block every save. Set required: false, ` +
+      `move the field to a custom-component section, or drop the required constraint.`,
+  );
+}
+
 // Tier 2.7e navigate rowAction → target-screen params validity. Shared by
 // entityList and projectionList (framework#1708) — projectionList has no
 // `screen.entity`, so there's no same-entity row["id"] auto-fill case: any
@@ -224,6 +267,15 @@ export function validateScreenShortIdCollisions(
   }
 }
 
+// redirect/cancelTarget accept either a same-feature short id (unchanged
+// behavior, qualified against the owning feature) or a fully-qualified
+// cross-feature screen QN (`<feature>:screen:<id>`) given verbatim — a
+// short id can never itself be a valid QN (QN_SEGMENT forbids colons), so
+// the two forms don't collide.
+function resolveScreenTargetQn(featureName: string, target: string): string {
+  return isValidQn(target) ? target : qualifyEntityName(featureName, "screen", target);
+}
+
 export function validateScreens(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
@@ -239,8 +291,9 @@ export function validateScreens(
   // der Runtime-Router (create-app) löst eine bare screenId app-weit über ALLE
   // Features auf (eine deklarative Liste im owning-Feature der Entity navigiert
   // so zu den Custom-Editoren der Consumer-App). Der Validator spiegelt das:
-  // same-feature ODER irgendein Feature. (redirect/cancelTarget bleiben bewusst
-  // same-feature: deren Router baut die URL direkt aus der kurzen id.)
+  // same-feature ODER irgendein Feature. redirect/cancelTarget akzeptieren
+  // zusätzlich eine voll-qualifizierte Cross-Feature-QN (resolveScreenTargetQn,
+  // #1946) — kurze IDs bleiben same-feature wie zuvor.
   const navTargetShortIds = screenShortIdsFrom(allScreenQns);
   for (const [screenId, screen] of Object.entries(feature.screens)) {
     if (screen.type === "custom") {
@@ -496,31 +549,29 @@ export function validateScreens(
       }
       validateWizardLayout(feature.name, screenId, "actionForm", screen.layout, featureMap);
       if (screen.redirect !== undefined) {
-        // redirect ist die kurze Screen-ID (z.B. "item-list"); der
-        // nav-Router resolved sie beim Mount gegen die Schema-Map.
-        // Cross-Feature-Redirect ist nicht supported — der nav-Router
-        // baut die URL aus screenId direkt, eine voll-QN würde als
-        // `/shop:screen:foo/` landen und nirgendwo greifen.
-        const candidateQn = qualifyEntityName(feature.name, "screen", screen.redirect);
+        // redirect ist entweder die kurze Screen-ID (same-feature, z.B.
+        // "item-list") oder eine voll-qualifizierte Cross-Feature-QN
+        // (`<feature>:screen:<id>`) — der Renderer strippt letztere beim
+        // Navigieren auf die kurze ID (lastSegment), die der nav-Router
+        // app-weit auflöst (#1946).
+        const candidateQn = resolveScreenTargetQn(feature.name, screen.redirect);
         if (!allScreenQns.has(candidateQn)) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (actionForm) redirect "${screen.redirect}" ` +
-              `does not resolve to a registered screen in this feature. Known screens: ${
-                [...Object.keys(feature.screens)].sort().join(", ") || "(none)"
-              }.`,
+              `does not resolve to a registered screen (checked "${candidateQn}"). Known screens ` +
+              `in this feature: ${[...Object.keys(feature.screens)].sort().join(", ") || "(none)"}.`,
           );
         }
       }
       if (typeof screen.cancelTarget === "string") {
         // Gleiche Regel wie redirect — `false` (kein Cancel-Button)
         // braucht keine Validierung.
-        const candidateQn = qualifyEntityName(feature.name, "screen", screen.cancelTarget);
+        const candidateQn = resolveScreenTargetQn(feature.name, screen.cancelTarget);
         if (!allScreenQns.has(candidateQn)) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (actionForm) cancelTarget "${screen.cancelTarget}" ` +
-              `does not resolve to a registered screen in this feature. Known screens: ${
-                [...Object.keys(feature.screens)].sort().join(", ") || "(none)"
-              }.`,
+              `does not resolve to a registered screen (checked "${candidateQn}"). Known screens ` +
+              `in this feature: ${[...Object.keys(feature.screens)].sort().join(", ") || "(none)"}.`,
           );
         }
       }
@@ -824,9 +875,22 @@ export function validateScreens(
               ),
             );
           }
+          validateNoWidgetRequiredField(feature.name, screenId, entityDef, normalized);
         }
       }
       validateWizardLayout(feature.name, screenId, "entityEdit", screen.layout, featureMap);
+      if (screen.redirect !== undefined) {
+        // Same rule as actionForm's redirect: short screen-ID (same-feature)
+        // or a fully-qualified cross-feature QN (#1946).
+        const candidateQn = resolveScreenTargetQn(feature.name, screen.redirect);
+        if (!allScreenQns.has(candidateQn)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) redirect "${screen.redirect}" ` +
+              `does not resolve to a registered screen (checked "${candidateQn}"). Known screens ` +
+              `in this feature: ${[...Object.keys(feature.screens)].sort().join(", ") || "(none)"}.`,
+          );
+        }
+      }
     }
   }
 }

package/src/engine/extension-names.ts

@@ -87,6 +87,23 @@ export const EXT_FILE_PROVIDER = "fileProvider" as const;
 // des file-foundation-Features MUSS diese Konstante mitziehen.
 export const FILE_PROVIDER_CONFIG_KEY = "file-foundation:config:provider" as const;
 
+/**
+ * `derivativeRenderer` — File-Derivative-Renderer-Plugin-Selection
+ * (file-derivatives).
+ *
+ * Renderer-Features (a future `derivatives-*` feature) register via
+ * `r.useExtension(EXT_DERIVATIVE_RENDERER, "<mimePattern>", { render })`,
+ * where `<mimePattern>` is an exact MIME type (`application/pdf`) or a
+ * type-wildcard (`image/*`). `ctx.derivatives.variant(...)` resolves the
+ * renderer for a FileRef's MIME type at call time — exact match first,
+ * wildcard second.
+ *
+ * No `r.extensionSelector` and no config key: unlike `fileProvider`, the
+ * resolution is deterministic from the MIME type — no tenant ever picks a
+ * different image library for the same content type.
+ */
+export const EXT_DERIVATIVE_RENDERER = "derivativeRenderer" as const;
+
 /**
  * `searchAdapter` — Search-Adapter-Forget-Hooks (Meilisearch-Index-Cleanup
  * bei User-Forget oder Tenant-Destroy).

package/src/engine/index.ts

@@ -77,6 +77,7 @@ export type { EmitCtx } from "./event-helpers";
 export { emitEvent, typedPayload } from "./event-helpers";
 export type { KumikoExtensionName } from "./extension-names";
 export {
+  EXT_DERIVATIVE_RENDERER,
   EXT_EXTERNAL_RESOURCE,
   EXT_FILE_PROVIDER,
   EXT_INFRA_RESOURCE,

package/src/errors/__tests__/classes.test.ts

@@ -106,6 +106,45 @@ describe("ValidationError", () => {
     expect(err.cause).toBe(result.error);
   });
 
+  test("custom issue with params.i18nKey overrides the mechanical errors.validation.custom key", () => {
+    const schema = z.object({ name: z.string() }).superRefine((values, ctx) => {
+      if (values.name === "") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["name"],
+          message: '"name" is required.',
+          params: { i18nKey: "kumiko.validation.required" },
+        });
+      }
+    });
+    const result = schema.safeParse({ name: "" });
+    if (result.success) throw new Error("zod did not reject");
+
+    const err = validationErrorFromZod(result.error);
+    const fields = (err.details as { fields: Array<Record<string, unknown>> }).fields;
+    expect(fields[0]).toMatchObject({
+      code: "custom",
+      i18nKey: "kumiko.validation.required",
+    });
+  });
+
+  test("custom issue without params.i18nKey still falls back to errors.validation.custom", () => {
+    const schema = z.object({ name: z.string() }).superRefine((values, ctx) => {
+      if (values.name === "bad") {
+        ctx.addIssue({ code: "custom", path: ["name"], message: "not allowed" });
+      }
+    });
+    const result = schema.safeParse({ name: "bad" });
+    if (result.success) throw new Error("zod did not reject");
+
+    const err = validationErrorFromZod(result.error);
+    const fields = (err.details as { fields: Array<Record<string, unknown>> }).fields;
+    expect(fields[0]).toMatchObject({
+      code: "custom",
+      i18nKey: "errors.validation.custom",
+    });
+  });
+
   test('root-level zod issue maps to path "(root)"', () => {
     const schema = z.string();
     const result = schema.safeParse(123);

package/src/errors/zod-bridge.ts

@@ -30,13 +30,30 @@ export function validationErrorFromZod(error: ZodError): ValidationError {
     return {
       path: issue.path.map(String).join(".") || "(root)",
       code: issue.code,
-      i18nKey: `errors.validation.${issue.code}`,
+      i18nKey: resolveI18nKey(issue),
       ...(params && { params }),
     };
   });
   return new ValidationError({ fields }, { cause: error });
 }
 
+// Every zod code maps mechanically to `errors.validation.<code>` — except
+// `code: "custom"`, which is zod's one-size-fits-all bucket for every
+// `superRefine`/`refine` check in the codebase (e.g. schema-builder.ts's
+// totalsMatch check). Left mechanical, ALL of them would collapse onto the
+// same `errors.validation.custom` ("Invalid value.") key. A `superRefine`
+// that needs its own key sets `params.i18nKey` on the issue; this is the one
+// place that honors it. Keep in sync with the client-side mirror
+// (packages/headless/src/form/zod-bridge.ts) — a superRefine can run on
+// either side.
+function resolveI18nKey(issue: ZodIssue): string {
+  if (issue.code === "custom") {
+    const override = issue.params?.["i18nKey"];
+    if (typeof override === "string") return override;
+  }
+  return `errors.validation.${issue.code}`;
+}
+
 function extractIssueParams(issue: ZodIssue): Readonly<Record<string, unknown>> | undefined {
   // ZodIssue is a discriminated union with variant-specific params (minimum,
   // maximum, expected, …); reading them generically requires widening since