@cosmicdrift/kumiko-renderer 0.203.0 → 0.204.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.203.0",
+  "version": "0.204.1",
   "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.203.0",
-    "@cosmicdrift/kumiko-headless": "0.203.0",
+    "@cosmicdrift/kumiko-framework": "0.204.1",
+    "@cosmicdrift/kumiko-headless": "0.204.1",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"

package/src/app/layout-fields.ts

@@ -2,19 +2,19 @@ import type {
   EditFieldSpec,
   EntityEditScreenDefinition,
 } from "@cosmicdrift/kumiko-framework/ui-types";
-import { isExtensionEditSection, normalizeEditField } from "@cosmicdrift/kumiko-framework/ui-types";
+import { isFieldsEditSection, normalizeEditField } from "@cosmicdrift/kumiko-framework/ui-types";
 
 // Normalized field specs actually rendered by the screen's layout, extension
-// sections skipped. Both this and `layoutFieldNames` key off "rendered by
-// the layout" for the same reason: a field the user never sees gets no
-// chance to review/correct a value nor to fix a presence error
+// (and relatedList) sections skipped. Both this and `layoutFieldNames` key
+// off "rendered by the layout" for the same reason: a field the user never
+// sees gets no chance to review/correct a value nor to fix a presence error
 // (search-param merge, #1708; presence schema in form-schema.ts).
 export function layoutEditFields(
   screen: EntityEditScreenDefinition,
 ): readonly Exclude<EditFieldSpec, string>[] {
   const specs: Exclude<EditFieldSpec, string>[] = [];
   for (const section of screen.layout.sections) {
-    if (isExtensionEditSection(section)) continue;
+    if (!isFieldsEditSection(section)) continue;
     for (const spec of section.fields) {
       specs.push(normalizeEditField(spec));
     }

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

@@ -27,7 +27,7 @@ import type {
   ProjectionDetailScreenDefinition,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import {
-  isExtensionEditSection,
+  isFieldsEditSection,
   normalizeEditField,
   PROJECTION_DETAIL_ENTITY as PROJECTION_DETAIL_PSEUDO_ENTITY,
 } from "@cosmicdrift/kumiko-framework/ui-types";
@@ -38,7 +38,8 @@ import {
 export function synthesizeProjectionDetailEntity(layout: EditLayout): EntityDefinition {
   const fields: Record<string, { type: "text" }> = {};
   for (const section of layout.sections) {
-    if (isExtensionEditSection(section)) continue; // rejected at boot, defensive here
+    // relatedList and extension sections carry no `fields` to synthesize.
+    if (!isFieldsEditSection(section)) continue;
     for (const spec of section.fields) {
       fields[normalizeEditField(spec).field] = { type: "text" };
     }
@@ -52,7 +53,8 @@ export function synthesizeProjectionDetailScreen(
   screen: ProjectionDetailScreenDefinition,
 ): EntityEditScreenDefinition {
   const sections = screen.layout.sections.map((section) => {
-    if (isExtensionEditSection(section)) return section; // rejected at boot, defensive here
+    // relatedList and extension sections pass through unchanged.
+    if (!isFieldsEditSection(section)) return section;
     return {
       ...section,
       fields: section.fields.map((spec) => ({ ...normalizeEditField(spec), readOnly: true })),

package/src/components/related-list-section.tsx

@@ -0,0 +1,116 @@
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
+import type {
+  EditRelatedListSectionViewModel,
+  ListRowViewModel,
+  Translate,
+} from "@cosmicdrift/kumiko-headless";
+import { type ReactNode, useMemo } from "react";
+import { useNav } from "../app/nav";
+import { dispatcherErrorText } from "../app/write-failed-error";
+import { useQuery } from "../hooks/use-query";
+import { useTranslation } from "../i18n";
+import { usePrimitives } from "../primitives";
+import { RenderList } from "./render-list";
+
+const RELATED_LIST_PSEUDO_ENTITY = "__related-list__";
+
+// Same paged envelope as ProjectionListBody's PagedRows (kumiko-screen.tsx) —
+// duplicated locally because that type isn't exported (projectionList and
+// relatedList are independent query call-sites, not a shared abstraction).
+type PagedRows = {
+  readonly rows: Readonly<Record<string, unknown>>[];
+  readonly nextCursor: string | null;
+  readonly total?: number;
+};
+
+// Minimal EntityDefinition from the section's own columns — same shape as
+// projection-list-shim's synthesizeProjectionEntity, but relatedList columns
+// aren't sortable (no sort UI on this section, see RelatedListSection below).
+function synthesizeRelatedListEntity(
+  columns: EditRelatedListSectionViewModel["columns"],
+): EntityDefinition {
+  const fields: Record<string, { type: "text" }> = {};
+  for (const col of columns) {
+    fields[normalizeListColumn(col).field] = { type: "text" };
+  }
+  return { fields } as unknown as EntityDefinition;
+}
+
+export function RelatedListSection({
+  section,
+  parentId,
+  featureName,
+  translate,
+}: {
+  readonly section: EditRelatedListSectionViewModel;
+  readonly parentId: string;
+  readonly featureName: string;
+  readonly translate?: Translate;
+}): ReactNode {
+  const { Banner, Section } = usePrimitives();
+  const t = useTranslation();
+  const effectiveTranslate = translate ?? t;
+  const nav = useNav();
+
+  const entity = useMemo(() => synthesizeRelatedListEntity(section.columns), [section.columns]);
+  const listScreen = useMemo(
+    (): EntityListScreenDefinition => ({
+      // Empty id → RenderList's own toolbarTitle resolves to "" (its
+      // `screen:${id}.title` lookup misses and falls back to `id`) — this
+      // component renders the visible heading itself via `Section` below,
+      // so RenderList's toolbar carries none.
+      id: "",
+      type: "entityList",
+      entity: RELATED_LIST_PSEUDO_ENTITY,
+      columns: section.columns,
+    }),
+    [section.columns],
+  );
+
+  const payload = useMemo(
+    () => ({
+      [section.parentParam ?? "id"]: parentId,
+      ...(section.pageSize !== undefined && { limit: section.pageSize }),
+    }),
+    [section.parentParam, section.pageSize, parentId],
+  );
+
+  const rowsQuery = useQuery<PagedRows>(section.query, payload);
+
+  const rowClick = section.rowClick;
+  const onRowClick =
+    rowClick !== undefined
+      ? (row: ListRowViewModel) => {
+          const id = String(row.values[rowClick.idColumn ?? "id"] ?? "");
+          if (id === "") return;
+          nav.navigate({ entity: rowClick.entity, id });
+        }
+      : undefined;
+
+  return (
+    <Section title={section.title} testId={`related-list-${section.title}`}>
+      {rowsQuery.loading && rowsQuery.data === null ? (
+        <Banner padded variant="loading" testId="related-list-loading">
+          Loading…
+        </Banner>
+      ) : rowsQuery.error ? (
+        <Banner padded variant="error" testId="related-list-error">
+          {dispatcherErrorText(rowsQuery.error, effectiveTranslate)}
+        </Banner>
+      ) : (
+        <RenderList
+          screen={listScreen}
+          entity={entity}
+          rows={rowsQuery.data?.rows ?? []}
+          featureName={featureName}
+          translate={effectiveTranslate}
+          {...(onRowClick !== undefined && { onRowClick })}
+        />
+      )}
+    </Section>
+  );
+}

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

@@ -40,9 +40,9 @@ export function shouldNotifyCaller(
   return !(result.isSuccess && !extensionsPersisted);
 }
 
-// Extension sections skip the `fields` filter (their own field set, unrelated
-// to `field`-name filtering); a `fields` section left with zero fields after
-// filtering is dropped, not rendered empty.
+// Extension and relatedList sections skip the `fields` filter (neither has a
+// `field`-name set that filtering applies to); a `fields` section left with
+// zero fields after filtering is dropped, not rendered empty.
 export function filterEditSections(
   sections: readonly EditSectionViewModel[],
   fieldsFilter: readonly string[] | undefined,
@@ -51,7 +51,7 @@ export function filterEditSections(
   const filterSet = new Set(fieldsFilter);
   const result: EditSectionViewModel[] = [];
   for (const section of sections) {
-    if (section.kind === "extension") {
+    if (section.kind === "extension" || section.kind === "relatedList") {
       result.push(section);
       continue;
     }

package/src/components/render-edit.tsx

@@ -5,7 +5,7 @@ import type {
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import {
   evalFieldCondition,
-  isExtensionEditSection,
+  isFieldsEditSection,
   normalizeEditField,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import type {
@@ -31,6 +31,7 @@ import { formatWhen } from "../format-when";
 import { useForm } from "../hooks/use-form";
 import { useTranslation } from "../i18n";
 import { usePrimitives } from "../primitives";
+import { RelatedListSection } from "./related-list-section";
 import {
   filterEditSections,
   hasEditableSection,
@@ -253,7 +254,8 @@ function deriveFormFields<TValues extends FormValues, TCtx>(
 ): Record<string, FieldConditions<TValues, TCtx>> {
   const out: Record<string, FieldConditions<TValues, TCtx>> = {};
   for (const section of screen.layout.sections) {
-    if (isExtensionEditSection(section)) continue;
+    // relatedList carries no `fields` for the form-condition map either.
+    if (!isFieldsEditSection(section)) continue;
     for (const spec of section.fields) {
       const normalized = normalizeEditField(spec);
       out[normalized.field] = {
@@ -786,14 +788,19 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const filteredSections = useMemo(
     // A fully-hidden "fields" section (every field in it currently
     // condition-hidden) must not occupy a wizard step; it would render
-    // empty and block Back/Next on nothing. Extension sections carry no
-    // `visible` (they own their own dirty/save lifecycle), 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).
+    // empty and block Back/Next on nothing. Extension and relatedList
+    // sections carry no `visible` (they own their own lifecycle / run
+    // their own query), 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).
     () =>
       filterEditSections(vm.sections, fieldsFilter).filter(
-        (section) => section.kind === "extension" || section.fields.length === 0 || section.visible,
+        (section) =>
+          section.kind === "extension" ||
+          section.kind === "relatedList" ||
+          section.fields.length === 0 ||
+          section.visible,
       ),
     [vm.sections, fieldsFilter],
   );
@@ -1302,6 +1309,22 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
               </WizardStepGroup>
             );
           }
+          if (section.kind === "relatedList") {
+            // parentId is the displayed record's id — without it there's no
+            // parent row whose related rows could be queried (fw#2166).
+            // Rejected at boot in wizard layouts, so no WizardStepGroup here.
+            const parentId = resolveExtensionEntityId(entityIdProp, vm.id);
+            if (parentId === null) return null;
+            return (
+              <RelatedListSection
+                key={section.title}
+                section={section}
+                parentId={parentId}
+                featureName={featureName}
+                translate={translate}
+              />
+            );
+          }
           if (!section.visible) return null;
           // Section-Header unterdrücken wenn er den Form-Titel der
           // Action-Bar 1:1 wiederholen würde (typisch bei Single-Section-

package/src/index.ts

@@ -77,6 +77,7 @@ export { lastSegment } from "./app/qn";
 export type { VariableChipsProps } from "./app/variable-chips";
 export { VariableChips } from "./app/variable-chips";
 export { dispatcherErrorText, WriteFailedError } from "./app/write-failed-error";
+export { RelatedListSection } from "./components/related-list-section";
 export type {
   RenderEditAction,
   RenderEditChangeState,