@cosmicdrift/kumiko-renderer 0.354.0 → 0.355.0

package/dist/app/form-schema.d.ts

@@ -1,6 +1,7 @@
 import type { EntityDefinition, EntityEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type EditFormMode } from "@cosmicdrift/kumiko-headless";
 import * as z from "zod";
 export declare function isPresent(value: unknown): boolean;
 export declare const REQUIRED_FIELD_I18N_KEY = "kumiko.validation.required";
 export declare const OPTION_NOT_AVAILABLE_I18N_KEY = "kumiko.validation.optionNotAvailable";
-export declare function buildFormSchema(entity: EntityDefinition, screen: EntityEditScreenDefinition, unchangedFrom?: Readonly<Record<string, unknown>>): z.ZodType;
+export declare function buildFormSchema(entity: EntityDefinition, screen: EntityEditScreenDefinition, verb: EditFormMode, unchangedFrom?: Readonly<Record<string, unknown>>): z.ZodType;

package/dist/app/form-schema.js

@@ -17,6 +17,26 @@ function isEmbeddedListField(field) {
 // Renders raw to the user without a de+en default in i18n-defaults.ts.
 export const REQUIRED_FIELD_I18N_KEY = "kumiko.validation.required";
 export const OPTION_NOT_AVAILABLE_I18N_KEY = "kumiko.validation.optionNotAvailable";
+function isRequiredValueMissing(spec, field, record, unchangedFrom) {
+    // Screen-spec `required` overrides the entity default, mirroring
+    // `view-model/edit.ts` — the rendered form is the reference, and a
+    // presence check stricter than the form blocks the user for nothing.
+    const entityRequired = "required" in field && field.required === true;
+    const isRequired = spec.required === undefined ? entityRequired : evalFieldCondition(spec.required, record);
+    if (!isRequired)
+        return false;
+    // Embedded LIST fields get their own EmbeddedListField grid widget
+    // (#1838) — they're fillable, so NO_WIDGET_FIELD_TYPES's "embedded"
+    // entry must not exempt them. A statically-`required: true` field
+    // with no bound widget is also caught at boot
+    // (validateNoWidgetRequiredField in boot-validator/screens.ts).
+    if (NO_WIDGET_FIELD_TYPES.includes(field.type) && !isEmbeddedListField(field))
+        return false;
+    if (isPresent(record[spec.field]))
+        return false;
+    return !(unchangedFrom !== undefined &&
+        JSON.stringify(record[spec.field]) === JSON.stringify(unchangedFrom[spec.field]));
+}
 // Client-side presence validation for the auto-wired entityEdit path —
 // checks that every rendered required field HAS a value, not that the
 // value has the right shape. Format/range/type validation stays server-
@@ -41,12 +61,15 @@ export const OPTION_NOT_AVAILABLE_I18N_KEY = "kumiko.validation.optionNotAvailab
 // fields via `computeFieldStates(options.fields, …)` (form-controller.ts:163,181),
 // fed by `deriveFormFields(screen)` in render-edit.tsx.
 //
+// `verb` selects which `writeExcludedFields` list is skipped.
+//
 // `unchangedFrom` is for payloadMode "changes" (update): a field still equal to
 // its loaded value never reaches the payload, so the server never presence-
 // checks it — a legacy row with a now-required empty field must stay saveable
 // when the user edits something else.
-export function buildFormSchema(entity, screen, unchangedFrom) {
+export function buildFormSchema(entity, screen, verb, unchangedFrom) {
     const fields = layoutEditFields(screen);
+    const excludedFromWrite = new Set(screen.writeExcludedFields?.[verb] ?? []);
     return z
         .object({})
         .passthrough()
@@ -60,31 +83,16 @@ export function buildFormSchema(entity, screen, unchangedFrom) {
             const field = entity.fields[spec.field];
             if (!field)
                 continue;
+            // Hidden on create, read-only on update: the user cannot resolve a presence error.
+            if (excludedFromWrite.has(spec.field))
+                continue;
             // Not operable by the user — a presence error would be unresolvable,
             // same reason as the NO_WIDGET_FIELD_TYPES check below.
             if (spec.readOnly !== undefined && evalFieldCondition(spec.readOnly, record))
                 continue;
             selectFieldsToCheck[spec.field] = field;
-            // Screen-spec `required` overrides the entity default, mirroring
-            // `view-model/edit.ts` — the rendered form is the reference, and a
-            // presence check stricter than the form blocks the user for nothing.
-            const entityRequired = "required" in field && field.required === true;
-            const isRequired = spec.required === undefined ? entityRequired : evalFieldCondition(spec.required, record);
-            if (!isRequired)
-                continue;
-            // Embedded LIST fields get their own EmbeddedListField grid widget
-            // (#1838) — they're fillable, so NO_WIDGET_FIELD_TYPES's "embedded"
-            // entry must not exempt them. A statically-`required: true` field
-            // with no bound widget is also caught at boot
-            // (validateNoWidgetRequiredField in boot-validator/screens.ts).
-            if (NO_WIDGET_FIELD_TYPES.includes(field.type) && !isEmbeddedListField(field))
-                continue;
-            if (isPresent(record[spec.field]))
-                continue;
-            if (unchangedFrom !== undefined &&
-                JSON.stringify(record[spec.field]) === JSON.stringify(unchangedFrom[spec.field])) {
+            if (!isRequiredValueMissing(spec, field, record, unchangedFrom))
                 continue;
-            }
             ctx.addIssue({
                 code: "custom",
                 path: [spec.field],

package/dist/app/kumiko-screen.js

@@ -178,6 +178,13 @@ function entityWriteCommand(featureName, entity, verb) {
 function findEntityListScreen(schema, entityName) {
     return schema.screens.find((s) => s.type === "entityList" && s.entity === entityName);
 }
+// Unknown or deleted record id: a localized empty state with a way back
+// instead of a bare error banner. Composed from shared primitives so web and
+// native render it alike.
+function RecordNotFoundState({ translate, onBack, }) {
+    const { Card, Text, Button } = usePrimitives();
+    return (_jsxs(Card, { options: { padded: true }, testId: "kumiko-screen-record-missing", children: [_jsx(Text, { testId: "kumiko-screen-record-missing-title", children: translate("kumiko.record.not-found.title") }), _jsx(Text, { variant: "muted", children: translate("kumiko.record.not-found.hint") }), onBack !== undefined && (_jsx(Button, { variant: "secondary", onClick: onBack, testId: "kumiko-screen-record-missing-back", children: translate("kumiko.record.not-found.back") }))] }));
+}
 function useNavigateToListAfter(schema, entityName) {
     const nav = useNav();
     return useCallback(() => {
@@ -658,7 +665,7 @@ function EntityEditCreateBody({ schema, screen, entity, translate, onSaved, }) {
         moneyCurrencyOverrides,
         handoffValues,
     ]);
-    const formSchema = useMemo(() => buildFormSchema(entity, screen), [entity, screen]);
+    const formSchema = useMemo(() => buildFormSchema(entity, screen, "create"), [entity, screen]);
     const writeCommand = entityWriteCommand(schema.featureName, screen.entity, "create");
     const navigateToList = useNavigateToListAfter(schema, screen.entity);
     const handleCancel = useCallback(() => navigateToReturnOr(nav, returnTarget, navigateToList), [nav, returnTarget, navigateToList]);
@@ -714,11 +721,15 @@ function EntityEditCreateBody({ schema, screen, entity, translate, onSaved, }) {
 // `<feature>:write:<entity>:update` on submit. `buildPayload` shapes the
 // snapshot into Kumiko's update-event envelope `{ id, version, changes }`.
 function EntityEditUpdateBody({ schema, screen, entity, entityId, translate, onCopyLink, autoReloadOnSave, onDeleted, }) {
-    const { Banner, Text } = usePrimitives();
+    const { Banner } = usePrimitives();
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
     const detailQn = `${toKebab(schema.featureName)}:query:${toKebab(screen.entity)}:detail`;
     const detailQuery = useQuery(detailQn, { id: entityId });
+    const nav = useNav();
+    const navigateToList = useNavigateToListAfter(schema, screen.entity);
+    const returnTargetParam = useReturnTarget(screen.id);
+    const returnTarget = screen.singleton === true ? undefined : returnTargetParam;
     if (detailQuery.loading && detailQuery.data === null) {
         return (_jsx(Banner, { padded: true, variant: "loading", testId: "kumiko-screen-loading", children: "Loading\u2026" }));
     }
@@ -727,7 +738,10 @@ function EntityEditUpdateBody({ schema, screen, entity, entityId, translate, onC
     }
     const record = detailQuery.data;
     if (!record) {
-        return (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-screen-record-missing", children: ["Record ", _jsx(Text, { variant: "code", children: entityId }), " not found."] }));
+        const onBack = returnTarget !== undefined || findEntityListScreen(schema, screen.entity) !== undefined
+            ? () => navigateToReturnOr(nav, returnTarget, navigateToList)
+            : undefined;
+        return (_jsx(RecordNotFoundState, { translate: effectiveTranslate, ...(onBack !== undefined && { onBack }) }));
     }
     // Record-version als React-key: bei "Neu laden" refetched detail,
     // liefert neue version, und das Form remountet komplett. Ohne den
@@ -768,7 +782,7 @@ function EntityEditUpdateForm({ schema, screen, entity, entityId, record, onRelo
         }
         return out;
     }, [entity.fields, entityDefaultCurrency, moneyCurrencyOverrides, record]);
-    const formSchema = useMemo(() => buildFormSchema(entity, screen, initial), [entity, screen, initial]);
+    const formSchema = useMemo(() => buildFormSchema(entity, screen, "update", initial), [entity, screen, initial]);
     // Extension-Werte (z.B. customFields-jsonb) an extension-sections geben,
     // damit sie beim Edit den Bestand zeigen statt write-only zu sein.
     const extensionInitialValues = useMemo(() => {
@@ -2164,7 +2178,13 @@ function ProjectionDetailBody({ schema, screen, translate, entityId, }) {
     }
     const record = detailQuery.data;
     if (!record) {
-        return (_jsx(Banner, { padded: true, variant: "error", testId: "kumiko-screen-record-missing", children: screen.singleton === true ? ("Record not found.") : (_jsxs(_Fragment, { children: ["Record ", _jsx(Text, { variant: "code", children: entityId }), " not found."] })) }));
+        const backListScreen = screen.listScreenId ??
+            (screen.detailFor !== undefined
+                ? findEntityListScreen(schema, screen.detailFor)?.id
+                : undefined);
+        return (_jsx(RecordNotFoundState, { translate: effectiveTranslate, ...(backListScreen !== undefined && {
+                onBack: () => nav.navigate({ screenId: lastSegment(backListScreen) }),
+            }) }));
     }
     // Grouped into the head Card alongside title/status/metrics (fw#2713):
     // these are actions on the record the head shows, not on whichever tab is

package/dist/components/render-edit.js

@@ -329,9 +329,15 @@ export function RenderEdit(props) {
     // Submit-Config nur wenn der Caller einen writeCommand mitgibt; bei
     // customSubmit-Pfad kommt der Form-Controller ohne Submit-Wiring,
     // weil wir controller.submit() eh nicht rufen.
-    const omitFields = useMemo(() => layoutEditFields(screen)
-        .filter((spec) => spec.submit === false)
-        .map((spec) => spec.field), [screen]);
+    const writeVerb = isCreateMode ? "create" : "update";
+    // A write-excluded field must never reach the payload: the handler schema is
+    // z.never() for it, so even an unchanged read-only value would be rejected.
+    const omitFields = useMemo(() => [
+        ...layoutEditFields(screen)
+            .filter((spec) => spec.submit === false)
+            .map((spec) => spec.field),
+        ...(screen.writeExcludedFields?.[writeVerb] ?? []),
+    ], [screen, writeVerb]);
     const submitConfig = writeCommand !== undefined
         ? {
             type: writeCommand,
@@ -611,7 +617,8 @@ export function RenderEdit(props) {
         values: snapshot.values,
         translate,
         featureName,
-    }), [screen, entity, snapshot.values, translate, featureName]);
+        mode: writeVerb,
+    }), [screen, entity, snapshot.values, translate, featureName, writeVerb]);
     const filteredSections = useMemo(
     // A fully-hidden "fields" section (every field in it currently
     // condition-hidden) must not occupy a wizard step; it would render
@@ -620,11 +627,12 @@ export function RenderEdit(props) {
     // run their own query / own submit), so they always pass through. A
     // section with no fields at all (e.g. a review-only step) has
     // `visible: fields.some(...)` = false vacuously; that's "no fields to
-    // hide", not "hidden", so it stays too (fw#1901).
+    // hide", not "hidden", so it stays too (fw#1901). Unless the create
+    // exclusion emptied it: that would leave an empty wizard step / tab.
     () => filterEditSections(vm.sections, fieldsFilter).filter((section) => section.kind === "extension" ||
         section.kind === "relatedList" ||
         section.kind === "writeForm" ||
-        section.fields.length === 0 ||
+        (section.fields.length === 0 && section.emptiedByWriteExclusion !== true) ||
         section.visible), [vm.sections, fieldsFilter]);
     const allFieldsRequired = useMemo(() => {
         const fillable = filteredSections.flatMap((section) => section.kind === "fields"

package/dist/i18n-defaults.js

@@ -60,6 +60,9 @@ export const kumikoDefaultTranslations = {
         "kumiko.list.empty.title": "No entries yet.",
         "kumiko.list.empty.hint": "Create the first one to get started.",
         "kumiko.list.no-entries": "No entries.",
+        "kumiko.record.not-found.title": "This record was not found.",
+        "kumiko.record.not-found.hint": "It may have been deleted, or the link is no longer valid.",
+        "kumiko.record.not-found.back": "Back to list",
         "kumiko.list.end-of-list": "— End of list —",
         "kumiko.list.sort.label": "Sort",
         "kumiko.list.sort.unsorted": "Unsorted",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.354.0",
+  "version": "0.355.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,9 +15,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.354.0",
-    "@cosmicdrift/kumiko-headless": "0.354.0",
-    "@cosmicdrift/kumiko-types": "0.354.0",
+    "@cosmicdrift/kumiko-framework": "0.355.0",
+    "@cosmicdrift/kumiko-headless": "0.355.0",
+    "@cosmicdrift/kumiko-types": "0.355.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -28,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.354.0"
+    "@cosmicdrift/kumiko-locale-de": "0.355.0"
   },
   "repository": {
     "type": "git",