@cosmicdrift/kumiko-renderer 0.238.0 → 0.240.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.238.0",
+  "version": "0.240.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.238.0",
-    "@cosmicdrift/kumiko-headless": "0.238.0",
+    "@cosmicdrift/kumiko-framework": "0.240.0",
+    "@cosmicdrift/kumiko-headless": "0.240.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -27,7 +27,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.238.0"
+    "@cosmicdrift/kumiko-locale-de": "0.240.0"
   },
   "repository": {
     "type": "git",

package/src/app/__tests__/projection-detail-shim.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import type { ProjectionDetailScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { synthesizeProjectionDetailScreen } from "../projection-detail-shim";
+
+// Regression for the writeForm extension (fw editable-detail-screens): the
+// hard readOnly:true enforcement in synthesizeProjectionDetailScreen must
+// still apply to every ordinary fields-section, unchanged — a writeForm
+// section is the one deliberate exception (isFieldsEditSection excludes it,
+// same as relatedList/extension), it must pass through editable.
+describe("synthesizeProjectionDetailScreen", () => {
+  test("forces readOnly:true on a fields section, but leaves a writeForm section's own readOnly untouched", () => {
+    const screen: ProjectionDetailScreenDefinition = {
+      id: "order-detail",
+      type: "projectionDetail",
+      query: "orders:query:order:detail",
+      layout: {
+        sections: [
+          { title: "Basics", fields: [{ field: "name", readOnly: false }] },
+          {
+            kind: "writeForm",
+            title: "Add note",
+            fieldDefs: { note: { type: "text" } },
+            fields: [{ field: "note", readOnly: false }],
+            handler: "orders:write:add-note",
+          },
+        ],
+      },
+    };
+
+    const result = synthesizeProjectionDetailScreen(screen);
+
+    const [fieldsSection, writeFormSection] = result.layout.sections;
+    if (fieldsSection === undefined || !("fields" in fieldsSection) || "kind" in fieldsSection) {
+      throw new Error("expected the first section to stay a plain fields section");
+    }
+    expect(fieldsSection.fields[0]).toMatchObject({ field: "name", readOnly: true });
+
+    if (writeFormSection === undefined || writeFormSection.kind !== "writeForm") {
+      throw new Error("expected the second section to stay kind: writeForm, untouched");
+    }
+    expect(writeFormSection.fields[0]).toEqual({ field: "note", readOnly: false });
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -6,14 +6,11 @@ import type {
   EntityDefinition,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
-  IconKey,
   ListFacetSpec,
   ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
   RowAction,
   RowActionNavigate,
-  RowActionWriteHandler,
-  RowFieldExtractor,
   ScreenDefinition,
   ToolbarAction,
 } from "@cosmicdrift/kumiko-framework/ui-types";
@@ -39,8 +36,6 @@ import { useTranslation } from "../i18n";
 import {
   type DataTableFacet,
   type DataTableRowAction,
-  type DataTableRowActionMode,
-  shouldRenderActionsIconOnly,
   statusToneForValue,
   usePrimitives,
 } from "../primitives";
@@ -60,81 +55,20 @@ import {
 import { synthesizeProjectionEntity, synthesizeProjectionScreen } from "./projection-list-shim";
 import { lastSegment, toKebab } from "./qn";
 import { featureNameFromQualifiedScreenId, qualifyScreenId } from "./qualify-screen-id";
+import {
+  buildProjectionRowActions,
+  evalRowExtractor,
+  isWriteHandlerRowAction,
+  refetchAfterWrite,
+  resolveActionIcon,
+  rowActionModeFor,
+  runProjectionRowNavigate,
+  stringifyNavParams,
+} from "./row-actions";
 import { screenAccessAllows } from "./screen-access";
 import { SecretsEditBody } from "./secrets-edit-body";
 import { dispatcherErrorText, WriteFailedError } from "./write-failed-error";
 
-function evalRowExtractor(
-  extractor: RowFieldExtractor,
-  row: Record<string, unknown>,
-): Record<string, unknown> {
-  if ("pick" in extractor) {
-    return Object.fromEntries(extractor.pick.map((f) => [f, row[f]]));
-  }
-  return Object.fromEntries(Object.entries(extractor.map).map(([to, from]) => [to, row[from]]));
-}
-
-function isWriteHandlerRowAction(action: RowAction): action is RowActionWriteHandler {
-  return action.kind === "writeHandler" || action.kind === undefined;
-}
-
-// Part B (fw-ui-defaults): id-derived default icon for actions that never
-// declared one — a screen author still gets a recognizable glyph instead of
-// a bare label. Checked against the actually registered IconKey vocabulary
-// (nav-icon.ts) — no entry for verbs without a matching icon (e.g. "start",
-// "pause").
-const ACTION_ICON_BY_ID: Readonly<Partial<Record<string, IconKey>>> = {
-  delete: "trash",
-  edit: "pencil",
-  create: "plus",
-  new: "plus",
-  add: "plus",
-  view: "eye",
-  open: "eye",
-  cancel: "x",
-  reject: "x",
-  complete: "check",
-  resolve: "check",
-  approve: "check",
-  archive: "archive",
-  publish: "upload",
-  duplicate: "copy",
-  copy: "copy",
-  download: "download",
-  refresh: "refresh",
-  retry: "refresh",
-  settings: "settings",
-  share: "share",
-  send: "send",
-};
-
-// Ids are kebab-case (RowAction.id doc) — a compound id whose full form has
-// no entry falls back to its last segment ("order-ship" -> "ship").
-function kebabLastSegment(id: string): string {
-  const idx = id.lastIndexOf("-");
-  return idx === -1 ? id : id.slice(idx + 1);
-}
-
-// Resolution order: author-declared `icon` wins, then the id-derived
-// default (full id, then its last kebab segment). `declared` is `undefined`
-// for ToolbarAction, which has no author-facing icon field.
-function resolveActionIcon(id: string, declared?: IconKey): IconKey | undefined {
-  if (declared !== undefined) return declared;
-  return ACTION_ICON_BY_ID[id] ?? ACTION_ICON_BY_ID[kebabLastSegment(id)];
-}
-
-// Row-action column mode for a resolved action set: a group where every
-// member carries an icon renders inline so `shouldRenderActionsIconOnly`
-// can collapse it to icon-only buttons (fw#2580). Anything else keeps the
-// DataTable's adaptive default (kebab past two actions) — inline text
-// buttons for an icon-less group are the very thing the collapse avoids.
-function rowActionModeFor(
-  actions: readonly DataTableRowAction[] | undefined,
-): DataTableRowActionMode | undefined {
-  if (actions === undefined || !shouldRenderActionsIconOnly(actions)) return undefined;
-  return "inline";
-}
-
 // KumikoScreen picks up a ScreenDefinition from the schema by qn and
 // routes it to the right renderer based on `screen.type`. Command
 // qualification (`<feature>:write:<entity>:create` etc.) happens here
@@ -1106,26 +1040,10 @@ function buildFilterFacets(specs: readonly ResolvedFacetSpec[]): DataTableFacet[
 // passes through any field present in entity.fields, matching its
 // pre-fw#2224 behavior; only the boolean-coercion branch cares about type.
 
-function stringifyNavParams(params: Record<string, unknown>): Record<string, string | null> {
-  const out: Record<string, string | null> = {};
-  for (const [k, v] of Object.entries(params)) {
-    out[k] =
-      v === null || v === undefined ? null : Array.isArray(v) ? JSON.stringify(v) : String(v);
-  }
-  return out;
-}
-
 function isFacetI18nKey(label: string): boolean {
   return !/\s/.test(label) && (label.includes(".") || label.includes(":"));
 }
 
-async function refetchAfterWrite(refetch: () => Promise<unknown>): Promise<void> {
-  await refetch().catch((err: unknown) => {
-    // biome-ignore lint/suspicious/noConsole: refetch must not poison the write-action error path
-    console.error("kumiko-screen: refetch after write action failed", err);
-  });
-}
-
 function buildFilterPayload(
   urlFilters: Readonly<Record<string, readonly string[]>>,
   typeOf: (field: string) => string | undefined,
@@ -1953,97 +1871,31 @@ function ProjectionListBody({
 
   const filterFacets = useMemo<DataTableFacet[]>(() => buildFilterFacets(facetSpecs), [facetSpecs]);
 
+  // Entity-Targets (fw#2228) — see EntityListBody.runNavigate for why the
+  // resolution happens in the NavApi impl. Unlike there: NO row["id"]
+  // fallback — projectionList rows come from an arbitrary query projection
+  // with no guaranteed "id" field. The boot validator therefore enforces an
+  // explicit entityId for projectionList entity targets. Same helper
+  // relatedList's rowActions reuse (related-list-section.tsx) — a
+  // projectionDetail relatedList row has the identical "no guaranteed id"
+  // shape.
   const runNavigate = useCallback(
-    (action: RowActionNavigate, row: ListRowViewModel) => {
-      if (action.entity !== undefined) {
-        // Entity-Targets (fw#2228) — siehe EntityListBody.runNavigate für die
-        // Begründung, warum die Auflösung in der NavApi-Impl passiert. Anders
-        // als dort: KEIN row["id"]-Fallback — projectionList-Rows kommen aus
-        // einer beliebigen Query-Projection ohne garantiertes "id"-Feld
-        // (gleiche Begründung wie beim screen-Target unten). Der Boot-
-        // Validator erzwingt deshalb einen expliziten entityId für
-        // projectionList-entity-Targets.
-        const id = action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : "";
-        if (id === "") return;
-        nav.navigate({ entity: action.entity, id });
-      } else if (action.screen !== undefined) {
-        const entityId =
-          action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : undefined;
-        nav.navigate({
-          screenId: action.screen,
-          ...(entityId !== undefined && entityId !== "" && { entityId }),
-        });
-      } else {
-        return;
-      }
-      const params =
-        action.params !== undefined ? evalRowExtractor(action.params, row.values) : undefined;
-      if (params !== undefined) {
-        nav.setSearchParams(stringifyNavParams(params));
-      }
-    },
+    (action: RowActionNavigate, row: ListRowViewModel) =>
+      runProjectionRowNavigate(nav, action, row),
     [nav],
   );
 
-  const rowActions = useMemo((): readonly DataTableRowAction[] | undefined => {
-    if (screen.rowActions === undefined) return undefined;
-    const out: DataTableRowAction[] = [];
-    for (const action of screen.rowActions) {
-      if (action.kind === "navigate") {
-        const navigateAction = action;
-        const visible = action.visible;
-        const actionIcon = resolveActionIcon(action.id, action.icon);
-        out.push({
-          id: action.id,
-          label: effectiveTranslate(action.label),
-          ...(action.style !== undefined && { style: action.style }),
-          ...(actionIcon !== undefined && { icon: actionIcon }),
-          onTrigger: (row: ListRowViewModel) => runNavigate(navigateAction, row),
-          ...(visible !== undefined && {
-            isVisible: (row: ListRowViewModel) => evalFieldCondition(visible, row.values),
-          }),
-        });
-        continue;
-      }
-      // writeHandler (default-kind) — gleicher Dispatch-Pfad wie entityList:
-      // Failure-Result MUSS zum Error werden (sonst schließt der Confirm-
-      // Dialog kommentarlos).
-      if (dispatcher === undefined) continue;
-      const writeAction = action;
-      const writeVisible = writeAction.visible;
-      out.push({
-        id: writeAction.id,
-        label: effectiveTranslate(writeAction.label),
-        ...(writeAction.style !== undefined && { style: writeAction.style }),
-        icon: resolveActionIcon(writeAction.id, writeAction.icon),
-        ...(writeAction.confirm !== undefined && {
-          confirm: effectiveTranslate(writeAction.confirm),
-        }),
-        ...(writeAction.confirmLabel !== undefined && {
-          confirmLabel: effectiveTranslate(writeAction.confirmLabel),
-        }),
-        onTrigger: async (row: ListRowViewModel) => {
-          const payload =
-            writeAction.payload !== undefined
-              ? evalRowExtractor(writeAction.payload, row.values)
-              : { id: row.values["id"] };
-          const result = await dispatcher.write(writeAction.handler, payload);
-          if (!result.isSuccess) {
-            throw new WriteFailedError(
-              result.error,
-              dispatcherErrorText(result.error, effectiveTranslate),
-            );
-          }
-          // Same refetch as EntityListBody's rowActions above.
-          await refetchAfterWrite(rowsQuery.refetch);
-        },
-        ...(writeVisible !== undefined && {
-          isVisible: (row: ListRowViewModel) => evalFieldCondition(writeVisible, row.values),
-        }),
-      });
-    }
-    return out.length > 0 ? out : undefined;
-  }, [screen.rowActions, effectiveTranslate, runNavigate, dispatcher, rowsQuery.refetch]);
+  const rowActions = useMemo(
+    () =>
+      buildProjectionRowActions({
+        rowActions: screen.rowActions,
+        translate: effectiveTranslate,
+        dispatcher,
+        nav,
+        refetch: rowsQuery.refetch,
+      }),
+    [screen.rowActions, effectiveTranslate, dispatcher, nav, rowsQuery.refetch],
+  );
 
   // Same icon-only collapse as entityList (fw#2580) — projectionList rows go
   // through the identical RenderList/DataTable path.
@@ -2255,6 +2107,18 @@ function ProjectionDetailBody({
     entityId !== undefined ? { [idParam]: entityId } : {},
   );
 
+  // A writeForm section's handler creates a new record (see EditWriteFormSection's
+  // doc) — both the outer record (header/metrics/other sections) and a sibling
+  // relatedList section's own independently-fetched rows must reflect it. A
+  // query refetch alone only refreshes `record` below; bumping this into
+  // <RenderEdit>'s `key` forces a full remount so RelatedListSection's own
+  // useQuery call re-runs too (it has no `live` subscription of its own).
+  const [reloadNonce, setReloadNonce] = useState(0);
+  const reloadDetail = useCallback(async () => {
+    await detailQuery.refetch();
+    setReloadNonce((n) => n + 1);
+  }, [detailQuery.refetch]);
+
   // Default edit action (fw#2166): resolved cross-feature over ALL mounted
   // features, not just this feature's own schema — detailFor itself is
   // resolved cross-feature by the boot-validator (detail-screens.ts), and
@@ -2528,12 +2392,14 @@ function ProjectionDetailBody({
   );
   return (
     <RenderEdit
+      key={`${entityId}:${reloadNonce}`}
       screen={detailScreen}
       entity={entity}
       featureName={schema.featureName}
       initial={record as FormValues}
       entityId={entityId}
       customSubmit={async () => ({ isSuccess: true, validationBlocked: false, data: undefined })}
+      onReload={reloadDetail}
       {...(headerActions !== undefined && { actions: headerActions })}
       {...(translate !== undefined && { translate })}
       {...(hasTabs && { hideSectionTitles: true })}

package/src/app/row-actions.ts

@@ -0,0 +1,201 @@
+import type {
+  IconKey,
+  RowAction,
+  RowActionNavigate,
+  RowActionWriteHandler,
+  RowFieldExtractor,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { evalFieldCondition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher, ListRowViewModel, Translate } from "@cosmicdrift/kumiko-headless";
+import type { DataTableRowAction, DataTableRowActionMode } from "../primitives";
+import { shouldRenderActionsIconOnly } from "../primitives";
+import type { NavApi } from "./nav";
+import { dispatcherErrorText, WriteFailedError } from "./write-failed-error";
+
+export function evalRowExtractor(
+  extractor: RowFieldExtractor,
+  row: Record<string, unknown>,
+): Record<string, unknown> {
+  if ("pick" in extractor) {
+    return Object.fromEntries(extractor.pick.map((f) => [f, row[f]]));
+  }
+  return Object.fromEntries(Object.entries(extractor.map).map(([to, from]) => [to, row[from]]));
+}
+
+export function isWriteHandlerRowAction(action: RowAction): action is RowActionWriteHandler {
+  return action.kind === "writeHandler" || action.kind === undefined;
+}
+
+// Part B (fw-ui-defaults): id-derived default icon for actions that never
+// declared one — a screen author still gets a recognizable glyph instead of
+// a bare label. Checked against the actually registered IconKey vocabulary
+// (nav-icon.ts) — no entry for verbs without a matching icon (e.g. "start",
+// "pause").
+const ACTION_ICON_BY_ID: Readonly<Partial<Record<string, IconKey>>> = {
+  delete: "trash",
+  edit: "pencil",
+  create: "plus",
+  new: "plus",
+  add: "plus",
+  view: "eye",
+  open: "eye",
+  cancel: "x",
+  reject: "x",
+  complete: "check",
+  resolve: "check",
+  approve: "check",
+  archive: "archive",
+  publish: "upload",
+  duplicate: "copy",
+  copy: "copy",
+  download: "download",
+  refresh: "refresh",
+  retry: "refresh",
+  settings: "settings",
+  share: "share",
+  send: "send",
+};
+
+// Ids are kebab-case (RowAction.id doc) — a compound id whose full form has
+// no entry falls back to its last segment ("order-ship" -> "ship").
+function kebabLastSegment(id: string): string {
+  const idx = id.lastIndexOf("-");
+  return idx === -1 ? id : id.slice(idx + 1);
+}
+
+// Resolution order: author-declared `icon` wins, then the id-derived
+// default (full id, then its last kebab segment). `declared` is `undefined`
+// for ToolbarAction, which has no author-facing icon field.
+export function resolveActionIcon(id: string, declared?: IconKey): IconKey | undefined {
+  if (declared !== undefined) return declared;
+  return ACTION_ICON_BY_ID[id] ?? ACTION_ICON_BY_ID[kebabLastSegment(id)];
+}
+
+// Row-action column mode for a resolved action set: a group where every
+// member carries an icon renders inline so `shouldRenderActionsIconOnly`
+// can collapse it to icon-only buttons (fw#2580). Anything else keeps the
+// DataTable's adaptive default (kebab past two actions) — inline text
+// buttons for an icon-less group are the very thing the collapse avoids.
+export function rowActionModeFor(
+  actions: readonly DataTableRowAction[] | undefined,
+): DataTableRowActionMode | undefined {
+  if (actions === undefined || !shouldRenderActionsIconOnly(actions)) return undefined;
+  return "inline";
+}
+
+export function stringifyNavParams(params: Record<string, unknown>): Record<string, string | null> {
+  const out: Record<string, string | null> = {};
+  for (const [k, v] of Object.entries(params)) {
+    out[k] =
+      v === null || v === undefined ? null : Array.isArray(v) ? JSON.stringify(v) : String(v);
+  }
+  return out;
+}
+
+export async function refetchAfterWrite(refetch: () => Promise<unknown>): Promise<void> {
+  await refetch().catch((err: unknown) => {
+    // biome-ignore lint/suspicious/noConsole: refetch must not poison the write-action error path
+    console.error("kumiko-screen: refetch after write action failed", err);
+  });
+}
+
+// Navigate execution for query-driven rows (projectionList, and relatedList
+// — both have no guaranteed "id" field, unlike entityList's rows which back
+// a real entity). No same-entity row["id"] fallback (see EntityListBody's
+// own runNavigate for that variant, which stays separate — entityList's
+// fallback needs `screen.entity`, which neither projectionList nor
+// relatedList has).
+export function runProjectionRowNavigate(
+  nav: NavApi,
+  action: RowActionNavigate,
+  row: ListRowViewModel,
+): void {
+  if (action.entity !== undefined) {
+    const id = action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : "";
+    // skip: no entityId column on this row — nothing to navigate to.
+    if (id === "") return;
+    nav.navigate({ entity: action.entity, id });
+  } else if (action.screen !== undefined) {
+    const entityId =
+      action.entityId !== undefined ? String(row.values[action.entityId] ?? "") : undefined;
+    nav.navigate({
+      screenId: action.screen,
+      ...(entityId !== undefined && entityId !== "" && { entityId }),
+    });
+  } else {
+    // skip: neither entity nor screen set — the boot-validator rejects this
+    // shape (resolveRowActionNavigateTarget), so this only guards types.
+    return;
+  }
+  const params =
+    action.params !== undefined ? evalRowExtractor(action.params, row.values) : undefined;
+  if (params !== undefined) {
+    nav.setSearchParams(stringifyNavParams(params));
+  }
+}
+
+// Builds the DataTable-ready row-action set for a query-driven row source
+// (projectionList, relatedList) — navigate dispatches through
+// runProjectionRowNavigate, writeHandler dispatches through the shared
+// Dispatcher and refetches `refetch` on success. Single implementation so
+// projectionList's rowActions and a projectionDetail relatedList section's
+// rowActions can't drift apart (fw editable-detail-screens).
+export function buildProjectionRowActions(options: {
+  readonly rowActions: readonly RowAction[] | undefined;
+  readonly translate: Translate;
+  readonly dispatcher: Dispatcher | undefined;
+  readonly nav: NavApi;
+  readonly refetch: () => Promise<unknown>;
+}): readonly DataTableRowAction[] | undefined {
+  const { rowActions, translate, dispatcher, nav, refetch } = options;
+  if (rowActions === undefined) return undefined;
+  const out: DataTableRowAction[] = [];
+  for (const action of rowActions) {
+    if (action.kind === "navigate") {
+      const navigateAction = action;
+      const visible = action.visible;
+      const actionIcon = resolveActionIcon(action.id, action.icon);
+      out.push({
+        id: action.id,
+        label: translate(action.label),
+        ...(action.style !== undefined && { style: action.style }),
+        ...(actionIcon !== undefined && { icon: actionIcon }),
+        onTrigger: (row: ListRowViewModel) => runProjectionRowNavigate(nav, navigateAction, row),
+        ...(visible !== undefined && {
+          isVisible: (row: ListRowViewModel) => evalFieldCondition(visible, row.values),
+        }),
+      });
+      continue;
+    }
+    // writeHandler (default-kind) — a swallowed failure result must become a
+    // thrown error (fw prod-bug 2026-06-07), same as every other write path.
+    if (dispatcher === undefined) continue;
+    const writeAction = action;
+    const writeVisible = writeAction.visible;
+    out.push({
+      id: writeAction.id,
+      label: translate(writeAction.label),
+      ...(writeAction.style !== undefined && { style: writeAction.style }),
+      icon: resolveActionIcon(writeAction.id, writeAction.icon),
+      ...(writeAction.confirm !== undefined && { confirm: translate(writeAction.confirm) }),
+      ...(writeAction.confirmLabel !== undefined && {
+        confirmLabel: translate(writeAction.confirmLabel),
+      }),
+      onTrigger: async (row: ListRowViewModel) => {
+        const payload =
+          writeAction.payload !== undefined
+            ? evalRowExtractor(writeAction.payload, row.values)
+            : { id: row.values["id"] };
+        const result = await dispatcher.write(writeAction.handler, payload);
+        if (!result.isSuccess) {
+          throw new WriteFailedError(result.error, dispatcherErrorText(result.error, translate));
+        }
+        await refetchAfterWrite(refetch);
+      },
+      ...(writeVisible !== undefined && {
+        isVisible: (row: ListRowViewModel) => evalFieldCondition(writeVisible, row.values),
+      }),
+    });
+  }
+  return out.length > 0 ? out : undefined;
+}