@cosmicdrift/kumiko-renderer 0.202.0 → 0.204.0

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,
@@ -136,6 +137,12 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
    *  platform-neutrale Package darf kein `navigator`/`window` anfassen,
    *  siehe guard-renderer-boundaries). undefined = kein Button. */
   readonly onCopyLink?: () => Promise<void> | void;
+  /** Header action buttons, rendered before the built-in copy-link/
+   *  delete/cancel/save controls. Each callback is already fully
+   *  bound (screen-type/nav/dispatcher resolution happens in the caller,
+   *  same split as `onCopyLink`) — RenderEdit only wires the button, its
+   *  busy state and its confirm dialog. */
+  readonly actions?: readonly RenderEditAction[];
   /** i18n-key für den Submit-Button. Default: "kumiko.actions.save".
    *  Action-Forms (Tier 2.7d) übergeben hier ihren screen.submitLabel,
    *  damit "Speichern" durch domain-spezifischere Strings ersetzt
@@ -205,6 +212,15 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
   readonly hideActions?: boolean;
 };
 
+export type RenderEditAction = {
+  readonly id: string;
+  readonly label: string;
+  readonly onPress: () => void | Promise<void>;
+  readonly style?: "primary" | "secondary" | "danger";
+  readonly confirm?: string;
+  readonly confirmLabel?: string;
+};
+
 export type RenderEditChangeState<TValues extends FormValues> = {
   readonly values: TValues;
   readonly changes: Partial<TValues>;
@@ -238,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] = {
@@ -314,6 +331,72 @@ function ExtensionSectionMount({
   );
 }
 
+// One header action + its own busy/confirm state — same pattern as
+// render-list.tsx's ToolbarActionView (each RenderEditAction is
+// independently bound by the caller, there is no shared trigger pipeline
+// to hook into like the built-in onDelete/onSubmit paths have).
+function RenderEditActionButton({
+  action,
+  Button,
+  Dialog,
+  onError,
+}: {
+  readonly action: RenderEditAction;
+  readonly Button: ReturnType<typeof usePrimitives>["Button"];
+  readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
+  readonly onError: (text: string | null) => void;
+}): ReactNode {
+  const [busy, setBusy] = useState(false);
+  const [confirmOpen, setConfirmOpen] = useState(false);
+
+  const trigger = async (): Promise<void> => {
+    setBusy(true);
+    onError(null);
+    try {
+      await action.onPress();
+    } catch (e) {
+      onError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const variant = action.style ?? "secondary";
+  // Same rule as RowActionWriteHandler: "danger" forces a confirm even
+  // without an explicit confirm key.
+  const needsConfirm = action.confirm !== undefined || action.style === "danger";
+
+  return (
+    <>
+      <Button
+        type="button"
+        variant={variant}
+        loading={busy}
+        onClick={() => {
+          if (needsConfirm) {
+            setConfirmOpen(true);
+          } else {
+            void trigger();
+          }
+        }}
+        testId={`render-edit-action-${action.id}`}
+      >
+        {action.label}
+      </Button>
+      <Dialog
+        open={confirmOpen}
+        onOpenChange={setConfirmOpen}
+        title={action.label}
+        {...(action.confirm !== undefined && { description: action.confirm })}
+        confirmLabel={action.confirmLabel ?? action.label}
+        {...(action.style === "danger" && { variant: "danger" as const })}
+        onConfirm={trigger}
+        testId={`render-edit-action-${action.id}-dialog`}
+      />
+    </>
+  );
+}
+
 export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   props: RenderEditProps<TValues, TCtx>,
 ): ReactNode {
@@ -333,6 +416,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     onCancel,
     onReload,
     onCopyLink,
+    actions,
     submitLabel,
     labelAppendix,
     fieldAppendix,
@@ -362,6 +446,12 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const [linkCopied, setLinkCopied] = useState(false);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [formError, setFormError] = useState<DispatcherError | null>(null);
+  // One state for all header actions (actions?), not per-button — only one
+  // action can be in flight at a time, and this keeps the error surfaced in
+  // the shared formError-adjacent banner region instead of inside the
+  // button row (fw#2166 review: a full-width Banner there breaks the
+  // flex justify-end action bar).
+  const [actionError, setActionError] = useState<string | null>(null);
   const [rawStep, setRawStep] = useState(0);
   // Create-mode draftId (issue #1913) — resumed from `sessionStorage` (web)
   // on mount so a same-tab reload finds the right one of several parallel
@@ -698,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],
   );
@@ -985,6 +1080,15 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // gegen Fehlklicks. Save bleibt rechts (primary affordance).
   const formActions = (
     <>
+      {actions?.map((action) => (
+        <RenderEditActionButton
+          key={action.id}
+          action={action}
+          Button={Button}
+          Dialog={Dialog}
+          onError={setActionError}
+        />
+      ))}
       {onCopyLink !== undefined && (
         <Button
           type="button"
@@ -1205,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-
@@ -1282,6 +1402,11 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
             <Text testId="render-edit-extension-error-key">{translate(extensionErrorKey)}</Text>
           </Banner>
         )}
+        {actionError !== null && (
+          <Banner variant="error" testId="render-edit-action-error">
+            {actionError}
+          </Banner>
+        )}
         {onDelete !== undefined && (
           <Dialog
             open={confirmDeleteOpen}

package/src/index.ts

@@ -77,7 +77,9 @@ 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,
   RenderEditControls,
   RenderEditProps,