@cosmicdrift/kumiko-renderer 0.57.2 → 0.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.57.2",
+  "version": "0.60.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,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.55.1",
-    "@cosmicdrift/kumiko-headless": "0.55.1",
+    "@cosmicdrift/kumiko-framework": "0.57.2",
+    "@cosmicdrift/kumiko-headless": "0.57.2",
     "react": "^19.2.6"
   },
   "devDependencies": {

package/src/components/__tests__/render-edit-logic.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import type { DispatcherError, SubmitResult } from "@cosmicdrift/kumiko-headless";
+import { resolveExtensionEntityId, shouldNotifyCaller } from "../render-edit-logic";
+
+const error: DispatcherError = {
+  code: "internal_error",
+  httpStatus: 500,
+  i18nKey: "kumiko.errors.internal",
+  message: "boom",
+};
+
+const success: SubmitResult<unknown> = { validationBlocked: false, isSuccess: true, data: {} };
+const writeFailure: SubmitResult<unknown> = { validationBlocked: false, isSuccess: false, error };
+const validationBlocked: SubmitResult<unknown> = { validationBlocked: true, isSuccess: false };
+
+describe("resolveExtensionEntityId", () => {
+  test("explicit id prop wins over vm.id", () => {
+    expect(resolveExtensionEntityId("entity-42", "row-7")).toBe("entity-42");
+  });
+
+  // The #345/1 regression: mount fell back to vm.id but persist did not, so a
+  // custom-fields section mounted editable against the existing row yet saved
+  // to null → silent data loss. Both sites now resolve this same value.
+  test("undefined prop → vm.id fallback (update form carries the row id)", () => {
+    expect(resolveExtensionEntityId(undefined, "row-42")).toBe("row-42");
+  });
+
+  test("undefined prop + no vm.id (create mode) → null", () => {
+    expect(resolveExtensionEntityId(undefined, null)).toBeNull();
+  });
+
+  test("explicit null prop forces null even when vm.id is present", () => {
+    expect(resolveExtensionEntityId(null, "row-42")).toBeNull();
+  });
+});
+
+describe("shouldNotifyCaller", () => {
+  // The one case the #345/1 fix changes: a successful entity write whose
+  // extension persist failed must NOT notify (caller would navigate away and
+  // unmount the extension-error banner → silent custom-field data loss). The
+  // pre-fix code notified unconditionally, so this row flips false↔true.
+  test("entity success + extension persist failed → suppress callback", () => {
+    expect(shouldNotifyCaller(success, false)).toBe(false);
+  });
+
+  test("entity success + extensions persisted → notify", () => {
+    expect(shouldNotifyCaller(success, true)).toBe(true);
+  });
+
+  test("entity write failure → notify (caller needs the error result)", () => {
+    expect(shouldNotifyCaller(writeFailure, true)).toBe(true);
+    // extensions never run on a failed entity write, but the flag must not
+    // swallow the failure callback regardless of its value.
+    expect(shouldNotifyCaller(writeFailure, false)).toBe(true);
+  });
+
+  test("validation blocked → notify", () => {
+    expect(shouldNotifyCaller(validationBlocked, true)).toBe(true);
+  });
+});

package/src/components/render-edit-logic.ts

@@ -0,0 +1,28 @@
+import type { SubmitResult } from "@cosmicdrift/kumiko-headless";
+
+// Single source of truth for the extension-section entity-id. The section mount
+// and persistExtensions MUST resolve the same id — otherwise a section mounts
+// editable against one id (vm.id) while the persist step writes to (or skips)
+// another (null), silently dropping the user's input. An explicit `null` prop
+// forces "no entity" (no extension persistence); an omitted prop (undefined)
+// falls back to vm.id (= values["id"]), which the update form carries for the
+// existing row, so editing custom fields on that row actually persists.
+export function resolveExtensionEntityId(
+  entityIdProp: string | null | undefined,
+  vmId: string | null,
+): string | null {
+  return entityIdProp !== undefined ? entityIdProp : vmId;
+}
+
+// After a submit, decide whether to invoke the caller's onSubmit. The success
+// callback typically navigates away, which unmounts the extension-error banner.
+// Suppress the callback ONLY when the entity write succeeded but an extension-
+// section persist failed: the user must stay on the form to see the banner and
+// retry. Every other case still notifies the caller — entity failures and
+// validation blocks carry information the caller needs.
+export function shouldNotifyCaller(
+  result: SubmitResult<unknown>,
+  extensionsPersisted: boolean,
+): boolean {
+  return !(result.isSuccess && !extensionsPersisted);
+}

package/src/components/render-edit.tsx

@@ -28,6 +28,7 @@ import { extensionSectionName, useExtensionSectionComponent } from "../app/exten
 import { useForm } from "../hooks/use-form";
 import { useTranslation } from "../i18n";
 import { usePrimitives } from "../primitives";
+import { resolveExtensionEntityId, shouldNotifyCaller } from "./render-edit-logic";
 import { RenderField } from "./render-field";
 
 // End-to-end renderer für einen entityEdit screen. Rendert aus-
@@ -40,12 +41,13 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
   readonly entity: EntityDefinition;
   readonly featureName: string;
   readonly initial: TValues;
-  /** Echte entity-id für extension-section-Mounts (Set-Value-UI). Der
-   *  Update-Body kennt sie aus der Route; ohne sie fiele die Section auf
-   *  `vm.id` (= values["id"]) zurück, das im Update-Form immer fehlt
-   *  (id ist keine deklarierte Form-Field, siehe EntityEditUpdateForm) —
-   *  die Section bliebe dann fälschlich im create-mode. Weglassen
-   *  (undefined) = create-mode / kein extension-Kontext (vm.id-Fallback). */
+  /** Echte entity-id für extension-section-Mounts (Set-Value-UI). Mount UND
+   *  persistExtensions lösen sie über `resolveExtensionEntityId(entityIdProp,
+   *  vm.id)` auf — denselben Wert, damit die Section nicht editierbar gegen eine
+   *  id mountet während Persist gegen eine andere (oder gar nicht) schreibt.
+   *  Weglassen (undefined) = Fallback auf `vm.id` (= values["id"]), das das
+   *  Update-Form für die bestehende Row trägt. Explizites `null` = "keine
+   *  entity" (create-mode / keine extension-Persistenz). */
   readonly entityId?: string | null;
   /** Bereits gespeicherte Extension-Werte (z.B. `record.customFields`) für
    *  extension-section-Mounts. Erlaubt der Section, den Bestand beim Edit
@@ -245,7 +247,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // false = eine Section schlug fehl (ihr i18n-Key landet im Banner). Ohne
   // Entity-Kontext (create-mode ohne route-id) gibt es nichts zu schreiben.
   async function persistExtensions(): Promise<boolean> {
-    const entityId = entityIdProp ?? null;
+    const entityId = resolveExtensionEntityId(entityIdProp, vm.id);
     if (entityId === null) return true;
     const results = await runExtensionSubmits({ entityId });
     const failed = results.find((r) => !r.isSuccess);
@@ -304,14 +306,18 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       }
       // Form-level Errors (ohne field-level details) landen im Banner.
       // Field-Errors fließen über snapshot.errors in die einzelnen Fields.
+      let extensionsPersisted = true;
       if (result.isSuccess) {
         setFormError(null);
-        await persistExtensions();
+        extensionsPersisted = await persistExtensions();
       } else if (!result.validationBlocked) {
         const fieldIssues = result.error.details?.fields ?? [];
         setFormError(fieldIssues.length === 0 ? result.error : null);
       }
-      onSubmit?.(result);
+      // skip: on entity-success-but-extension-failure the extension-error
+      // banner is showing — don't notify (the caller navigates away on success
+      // and would unmount it before the user sees the failure).
+      if (shouldNotifyCaller(result, extensionsPersisted)) onSubmit?.(result);
     } finally {
       setIsSubmitting(false);
     }
@@ -376,7 +382,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
                 key={section.title}
                 section={section}
                 entityName={vm.entityName}
-                entityId={entityIdProp !== undefined ? entityIdProp : vm.id}
+                entityId={resolveExtensionEntityId(entityIdProp, vm.id)}
                 initialValues={extensionInitialValues}
               />
             );

package/src/components/render-list.tsx

@@ -352,6 +352,18 @@ function ListHeaderSlotMount({
   const header = screen.slots?.header;
   const name = header !== undefined ? extensionSectionName(header) : undefined;
   const Component = useExtensionSectionComponent(name);
+  // A declared-but-unregistered header slot renders nothing; warn so the author
+  // finds the typo / missing clientFeatures.extensionSectionComponents entry,
+  // mirroring the diagnostic banner in render-edit's ExtensionSectionMount
+  // (the toolbar has no room for a banner, so a dev-warn it is).
+  useEffect(() => {
+    if (name !== undefined && Component === undefined) {
+      // biome-ignore lint/suspicious/noConsole: dev-warning für Setup-Fehler
+      console.warn(
+        `[kumiko] List header slot component "${name}" on screen "${screen.id}" is not registered in clientFeatures.extensionSectionComponents — the header slot renders nothing.`,
+      );
+    }
+  }, [name, Component, screen.id]);
   if (Component === undefined) return null;
   return <Component entityName={screen.entity} entityId={null} />;
 }

package/src/i18n-defaults.ts

@@ -20,6 +20,9 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.actions.reload": "Neu laden",
     "kumiko.actions.create": "Neu",
 
+    // Version — Update-Awareness-Banner (UpdateChecker).
+    "kumiko.version.update-available": "Eine neue Version ist verfügbar.",
+
     // List — DataTable Toolbar, Empty-State, Search.
     "kumiko.list.search-placeholder": "Suchen…",
     "kumiko.list.empty.title": "Noch keine Einträge.",
@@ -99,6 +102,8 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.actions.reload": "Reload",
     "kumiko.actions.create": "New",
 
+    "kumiko.version.update-available": "A new version is available.",
+
     "kumiko.list.search-placeholder": "Search…",
     "kumiko.list.empty.title": "No entries yet.",
     "kumiko.list.empty.hint": "Create the first one to get started.",