@cosmicdrift/kumiko-renderer 0.269.2 → 0.273.0

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

@@ -15,12 +15,16 @@ import { useAppFeatures } from "../app/app-features-context";
 import {
   buildFilterFacets,
   buildFilterPayload,
+  mergeReferenceFacetOptions,
   resolveProjectionFacetSpecs,
 } from "../app/list-facets";
 import { useNav } from "../app/nav";
+import { ReferenceFacetBridges, type ReferenceFacetOption } from "../app/reference-facet-bridge";
+import { useReturnHost } from "../app/return-to";
 import {
   buildDefaultEditRowAction,
   buildProjectionRowActions,
+  buildProjectionToolbarActions,
   runProjectionRowNavigate,
 } from "../app/row-actions";
 import { findEditScreenFor } from "../app/screen-access";
@@ -63,6 +67,7 @@ function synthesizeRelatedListEntity(
 export function RelatedListSection({
   section,
   parentId,
+  record,
   featureName,
   translate,
   hideTitle,
@@ -70,6 +75,10 @@ export function RelatedListSection({
 }: {
   readonly section: EditRelatedListSectionViewModel;
   readonly parentId: string;
+  /** The enclosing projectionDetail's own record (the "Akte") — evaluates
+   *  toolbarActions' `visible`/`params` (RelatedListToolbarAction), the same
+   *  record header actions already use. */
+  readonly record: Readonly<Record<string, unknown>>;
   readonly featureName: string;
   readonly translate?: Translate;
   readonly hideTitle?: boolean;
@@ -85,6 +94,7 @@ export function RelatedListSection({
   const t = useTranslation();
   const effectiveTranslate = translate ?? t;
   const nav = useNav();
+  const host = useReturnHost();
   const dispatcher = useOptionalDispatcher();
   const appFeatures = useAppFeatures();
   const userRoles = useUserRoles();
@@ -120,19 +130,46 @@ export function RelatedListSection({
   const [filters, setFilters] = useState<Readonly<Record<string, readonly string[]>>>({});
 
   const facetSpecs = useMemo(
-    () => resolveProjectionFacetSpecs(section.facets, effectiveTranslate),
-    [section.facets, effectiveTranslate],
+    () => resolveProjectionFacetSpecs(section.facets, effectiveTranslate, featureName),
+    [section.facets, effectiveTranslate, featureName],
+  );
+  const [referenceFacetOptions, setReferenceFacetOptions] = useState<
+    Record<string, readonly ReferenceFacetOption[]>
+  >({});
+  const handleFacetOptions = useCallback(
+    (field: string, options: readonly ReferenceFacetOption[]) =>
+      setReferenceFacetOptions((prev) =>
+        prev[field] === options ? prev : { ...prev, [field]: options },
+      ),
+    [],
+  );
+  const resolvedFacetSpecs = useMemo(
+    () => mergeReferenceFacetOptions(facetSpecs, referenceFacetOptions),
+    [facetSpecs, referenceFacetOptions],
   );
   const filterPayload = useMemo(
     () =>
-      buildFilterPayload(filters, (field) => facetSpecs.find((spec) => spec.field === field)?.type),
-    [filters, facetSpecs],
+      buildFilterPayload(
+        filters,
+        (field) => resolvedFacetSpecs.find((spec) => spec.field === field)?.type,
+      ),
+    [filters, resolvedFacetSpecs],
+  );
+  const filterFacets = useMemo<DataTableFacet[]>(
+    () => buildFilterFacets(resolvedFacetSpecs),
+    [resolvedFacetSpecs],
   );
-  const filterFacets = useMemo<DataTableFacet[]>(() => buildFilterFacets(facetSpecs), [facetSpecs]);
 
   const payload = useMemo(
     () => ({
-      [section.parentParam ?? "id"]: parentId,
+      // `parentFilter` sends the parent id as a server-side `filter` clause
+      // instead of a bespoke top-level key — the generic `<entity>:list`
+      // query understands `filter`, not an arbitrary `parentParam` key. Kept
+      // separate from `filterPayload` (user facets) below so a facet
+      // selection can never clear or overwrite it.
+      ...(section.parentFilter !== undefined
+        ? { filter: { field: section.parentFilter.field, op: "eq" as const, value: parentId } }
+        : { [section.parentParam ?? "id"]: parentId }),
       ...(section.pageSize !== undefined && { limit: section.pageSize }),
       // Gated on the declared capability, not just on state carrying a value —
       // same rule as ProjectionListBody: a param the bound query's Zod schema
@@ -141,6 +178,7 @@ export function RelatedListSection({
       ...(section.facets !== undefined && filterPayload.length > 0 && { filters: filterPayload }),
     }),
     [
+      section.parentFilter,
       section.parentParam,
       section.pageSize,
       section.searchable,
@@ -197,7 +235,7 @@ export function RelatedListSection({
           nav.navigate({ entity: rowClick.entity, id });
         }
       : rowClickAction !== undefined
-        ? (row: ListRowViewModel) => runProjectionRowNavigate(nav, rowClickAction, row)
+        ? (row: ListRowViewModel) => runProjectionRowNavigate(nav, rowClickAction, row, host)
         : undefined;
 
   // Same execution path as projectionList's rowActions (kumiko-screen.tsx) —
@@ -214,6 +252,7 @@ export function RelatedListSection({
         refetch: rowsQuery.refetch,
         openDrawer: onOpenDrawer,
         defaultEditRowAction,
+        host,
       }),
     [
       section.rowActions,
@@ -223,6 +262,42 @@ export function RelatedListSection({
       rowsQuery.refetch,
       onOpenDrawer,
       defaultEditRowAction,
+      host,
+    ],
+  );
+
+  // Toolbar actions (e.g. "+ Create" above the tab table) — same schema
+  // and dispatch semantics as entityList/projectionList.
+  const toolbarActionButtons = useMemo(
+    () =>
+      buildProjectionToolbarActions({
+        toolbarActions: section.toolbarActions,
+        translate: effectiveTranslate,
+        dispatcher,
+        nav,
+        refetch: rowsQuery.refetch,
+        navigatePrefill:
+          section.parentFilter !== undefined
+            ? { [section.parentFilter.field]: parentId }
+            : { [section.parentParam ?? "id"]: parentId },
+        record,
+        host,
+        ...(onOpenDrawer !== undefined && {
+          openDrawer: (action) => onOpenDrawer(action, undefined),
+        }),
+      }),
+    [
+      section.toolbarActions,
+      section.parentParam,
+      section.parentFilter,
+      parentId,
+      record,
+      effectiveTranslate,
+      dispatcher,
+      nav,
+      host,
+      rowsQuery.refetch,
+      onOpenDrawer,
     ],
   );
 
@@ -273,18 +348,15 @@ export function RelatedListSection({
           })}
           {...(onRowClick !== undefined && { onRowClick })}
           {...(rowActions !== undefined && { rowActions })}
-          {...(hideTitle === true && { chromeless: true, scrollBody: true })}
+          {...(toolbarActionButtons !== undefined && { toolbarActions: toolbarActionButtons })}
+          {...(hideTitle === true && { scrollBody: true })}
         />
       </>
     );
 
   // hideTitle (tabs mode) → the tab panel is already the boundary: no
-  // Section card wrapper here, `chromeless` above drops the table's own
-  // card frame too, and `scrollBody` caps this wrapper at the panel's
-  // available height so a long Akte tab scrolls internally instead of
-  // stretching the page, while a short one still sizes to its content
-  // instead of stretching to the bottom (fw#2722, fw#2778) — the list sits
-  // directly in the tab. `FillContainer` is this section's
+  // Section card wrapper here — the table keeps its own frame to match the
+  // list-screen look; `scrollBody` caps it to the panel height. `FillContainer` is this section's
   // link in RenderEdit's `fillHeight` chain (see render-edit.tsx): it is
   // always this section's own root whenever hideTitle is set, since tabs
   // mode narrows RenderEdit to exactly this one active section. A platform
@@ -294,13 +366,23 @@ export function RelatedListSection({
   // Stacked (non-tabs) sections keep the card frame and document-flow
   // height since they render a visible title and aren't confined to a tab
   // panel.
+  const bridges = <ReferenceFacetBridges specs={facetSpecs} onOptions={handleFacetOptions} />;
+
   if (hideTitle) {
-    return FillContainer !== undefined ? <FillContainer>{content}</FillContainer> : content;
+    return (
+      <>
+        {bridges}
+        {FillContainer !== undefined ? <FillContainer>{content}</FillContainer> : content}
+      </>
+    );
   }
 
   return (
-    <Section title={section.title} testId={`related-list-${section.title}`}>
-      {content}
-    </Section>
+    <>
+      {bridges}
+      <Section title={section.title} testId={`related-list-${section.title}`}>
+        {content}
+      </Section>
+    </>
   );
 }

package/src/components/render-edit.tsx

@@ -340,6 +340,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const {
     Button,
     Banner,
+    Card,
     Dialog,
     Form,
     Section,
@@ -1177,9 +1178,13 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     return undefined;
   };
   const formTitle = resolveScreenText("title") ?? screen.id;
+  // screen.description is head-card copy, not tab content — in tabs mode
+  // (hideSectionTitles) the head card already carries title/subtitle/status.
   const formSubtitle =
     resolveScreenText("subtitle") ??
-    (screen.description !== undefined ? translate(screen.description) : undefined);
+    (hideSectionTitles !== true && screen.description !== undefined
+      ? translate(screen.description)
+      : undefined);
 
   return (
     <ExtensionFormRegistryProvider value={extensionFormRegistry}>
@@ -1334,6 +1339,8 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
                 key={section.title}
                 section={section}
                 parentId={parentId}
+                // @cast-boundary form-values: TValues ist strukturell ein Record.
+                record={snapshot.values as unknown as Readonly<Record<string, unknown>>}
                 featureName={featureName}
                 translate={translate}
                 hideTitle={hideSectionTitles}
@@ -1359,16 +1366,75 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
             );
           }
           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-
-          // ActionForms, deren Section-Label = Screen-Titel ist).
-          const sectionTitle = hideSectionTitles
-            ? undefined
-            : section.title === formTitle
-              ? undefined
-              : section.title;
           // Titellose Sections kollidieren sonst auf key/testId — Index-Fallback.
           const sectionKey = section.title ?? `section-${sectionIndex}`;
+          const renderFieldGrid = (
+            fields: readonly EditFieldViewModel[],
+            columns: number,
+            gridKey: string,
+          ): ReactNode => (
+            <Grid key={gridKey} columns={columns}>
+              {fields.map((field: EditFieldViewModel) => (
+                <GridCellForField
+                  key={field.field}
+                  field={disabled ? { ...field, readOnly: true } : field}
+                  columns={columns}
+                  issues={snapshot.errors[field.field]}
+                  onChange={(v) => {
+                    (controller.setField as (k: string, v: unknown) => void)(field.field, v);
+                  }}
+                  GridCell={GridCell}
+                  featureName={featureName}
+                  {...(labelAppendix !== undefined && {
+                    labelAppendix: labelAppendix(field.field),
+                  })}
+                  {...(fieldAppendix !== undefined && {
+                    fieldAppendix: fieldAppendix(field.field),
+                  })}
+                  allIssues={snapshot.errors}
+                  valueDisplay={valueDisplay}
+                  row={snapshot.values}
+                />
+              ))}
+            </Grid>
+          );
+          // Tabs mode renders one or more titled cards, so this card's actual
+          // heading doesn't visually duplicate the short Tab strip label.
+          if (hideSectionTitles === true) {
+            if (section.groups !== undefined) {
+              const groupsEl = (
+                <Grid key={sectionKey} columns={1}>
+                  {section.groups.map((group, groupIndex) => (
+                    <Card
+                      key={group.title}
+                      slots={{ title: group.title }}
+                      testId={`section-${sectionKey}-group-${groupIndex}`}
+                    >
+                      {renderFieldGrid(
+                        group.fields,
+                        group.columns,
+                        `${sectionKey}-group-${groupIndex}-grid`,
+                      )}
+                    </Card>
+                  ))}
+                </Grid>
+              );
+              return wrapWizardStep(sectionKey, groupsEl);
+            }
+            const cardEl = (
+              <Card
+                key={sectionKey}
+                {...(section.title !== undefined && { slots: { title: section.title } })}
+                testId={`section-${sectionKey}`}
+              >
+                {renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`)}
+              </Card>
+            );
+            return wrapWizardStep(sectionKey, cardEl);
+          }
+          // Suppress the section header when it would just repeat the form
+          // title verbatim (typical for single-section actionForms).
+          const sectionTitle = section.title === formTitle ? undefined : section.title;
           const sectionEl = (
             <Section
               key={sectionKey}
@@ -1377,30 +1443,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
               {...(section.icon !== undefined && { icon: section.icon })}
               testId={`section-${sectionKey}`}
             >
-              <Grid columns={section.columns}>
-                {section.fields.map((field: EditFieldViewModel) => (
-                  <GridCellForField
-                    key={field.field}
-                    field={disabled ? { ...field, readOnly: true } : field}
-                    columns={section.columns}
-                    issues={snapshot.errors[field.field]}
-                    onChange={(v) => {
-                      (controller.setField as (k: string, v: unknown) => void)(field.field, v);
-                    }}
-                    GridCell={GridCell}
-                    featureName={featureName}
-                    {...(labelAppendix !== undefined && {
-                      labelAppendix: labelAppendix(field.field),
-                    })}
-                    {...(fieldAppendix !== undefined && {
-                      fieldAppendix: fieldAppendix(field.field),
-                    })}
-                    allIssues={snapshot.errors}
-                    valueDisplay={valueDisplay}
-                    row={snapshot.values}
-                  />
-                ))}
-              </Grid>
+              {renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`)}
             </Section>
           );
           return wrapWizardStep(sectionKey, sectionEl);

package/src/index.ts

@@ -82,6 +82,15 @@ export {
   useNavigateWithInitialValues,
 } from "./app/nav";
 export { lastSegment } from "./app/qn";
+export type { ReturnHost } from "./app/return-to";
+export {
+  navigateWithReturnTo,
+  RETURN_TO_PARAM,
+  ReturnHostProvider,
+  resolveReturnTarget,
+  useReturnHost,
+  useReturnTarget,
+} from "./app/return-to";
 export type { EmbeddedScreenTarget } from "./app/use-embedded-screen";
 export { useEmbeddedScreen } from "./app/use-embedded-screen";
 export type { VariableChipsProps } from "./app/variable-chips";