@cosmicdrift/kumiko-renderer 0.246.0 → 0.247.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.246.0",
+  "version": "0.247.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.246.0",
-    "@cosmicdrift/kumiko-headless": "0.246.0",
+    "@cosmicdrift/kumiko-framework": "0.247.0",
+    "@cosmicdrift/kumiko-headless": "0.247.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.246.0"
+    "@cosmicdrift/kumiko-locale-de": "0.247.0"
   },
   "repository": {
     "type": "git",

package/src/app/row-actions.ts

@@ -159,6 +159,21 @@ type OpenDrawer = (
   initialValues: Readonly<Record<string, unknown>> | undefined,
 ) => void;
 
+// buildProjectionRowActions runs inside a useMemo (re-evaluated on every dep
+// change), so this dedupes the "openDrawer not wired" warning per action id
+// instead of firing on every recompute.
+const warnedDrawerRowActionIds = new Set<string>();
+
+function warnDrawerActionDropped(actionId: string): void {
+  // skip: already warned for this id — suppresses the repeat, not the warning itself.
+  if (warnedDrawerRowActionIds.has(actionId)) return;
+  warnedDrawerRowActionIds.add(actionId);
+  // biome-ignore lint/suspicious/noConsole: dev-warning for a setup error
+  console.warn(
+    `[kumiko] rowAction "${actionId}" is kind:"drawer", but the host did not wire openDrawer (RelatedListSection: pass onOpenDrawer) — it will not render.`,
+  );
+}
+
 function buildDrawerRowAction(
   action: RowActionDrawer,
   translate: Translate,
@@ -193,7 +208,8 @@ export function buildProjectionRowActions(options: {
   readonly nav: NavApi;
   readonly refetch: () => Promise<unknown>;
   /** Opens the drawer-kind action's target actionForm, prefilled from the
-   *  clicked row. Omitted callers (none today) simply drop drawer actions —
+   *  clicked row. Omitted callers (e.g. RelatedListSection embedded directly
+   *  without onOpenDrawer) drop drawer actions and get a dev warning —
    *  mirrors the `dispatcher === undefined` skip below for writeHandler. */
   readonly openDrawer?: OpenDrawer;
 }): readonly DataTableRowAction[] | undefined {
@@ -206,7 +222,10 @@ export function buildProjectionRowActions(options: {
       continue;
     }
     if (action.kind === "drawer") {
-      if (openDrawer === undefined) continue;
+      if (openDrawer === undefined) {
+        warnDrawerActionDropped(action.id);
+        continue;
+      }
       out.push(buildDrawerRowAction(action, translate, openDrawer));
       continue;
     }

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

@@ -1,7 +1,7 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 import type { RowAction } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Dispatcher, EditRelatedListSectionViewModel } from "@cosmicdrift/kumiko-headless";
-import { render, screen as rtlScreen, waitFor } from "@testing-library/react";
+import { fireEvent, render, screen as rtlScreen, waitFor } from "@testing-library/react";
 import type { ComponentType, ReactNode } from "react";
 import { type NavApi, NavProvider } from "../../app/nav";
 import { DispatcherProvider } from "../../context/dispatcher-context";
@@ -79,7 +79,10 @@ function testPrimitives(): CorePrimitives {
   } as unknown as CorePrimitives;
 }
 
-function stubDispatcher(rows: readonly Record<string, unknown>[] = [{ id: "r1", name: "Alice" }]): {
+function stubDispatcher(
+  rows: readonly Record<string, unknown>[] = [{ id: "r1", name: "Alice" }],
+  nextCursor: string | null = null,
+): {
   dispatcher: Dispatcher;
   writes: Array<{ type: string; payload: unknown }>;
   queryCount: () => number;
@@ -93,7 +96,7 @@ function stubDispatcher(rows: readonly Record<string, unknown>[] = [{ id: "r1",
     }) as Dispatcher["write"],
     query: (async () => {
       queryCalls += 1;
-      return { isSuccess: true, data: { rows, nextCursor: null } };
+      return { isSuccess: true, data: { rows, nextCursor } };
     }) as Dispatcher["query"],
     batch: (async () => ({ isSuccess: true, results: [] })) as Dispatcher["batch"],
     statusStore: {
@@ -168,11 +171,13 @@ function renderRelatedList(
 }
 
 describe("RelatedListSection — tabs-mode card chrome (fw#2722)", () => {
-  test("hideTitle (tabs mode) renders the list without a Section wrapper and marks the table chromeless", async () => {
+  test("hideTitle (tabs mode) renders the list without a Section wrapper and marks the table chromeless + scrollBody", async () => {
     const { dispatcher } = stubDispatcher();
     let capturedChromeless: boolean | undefined;
+    let capturedScrollBody: boolean | undefined;
     const capturingDataTable: ComponentType<DataTableProps> = (props) => {
       capturedChromeless = props.chromeless;
+      capturedScrollBody = props.scrollBody;
       return testDataTable(props);
     };
     render(
@@ -198,13 +203,16 @@ describe("RelatedListSection — tabs-mode card chrome (fw#2722)", () => {
     await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
     expect(rtlScreen.queryByTestId(`related-list-${historySection.title}`)).toBeNull();
     expect(capturedChromeless).toBe(true);
+    expect(capturedScrollBody).toBe(true);
   });
 
-  test("without hideTitle (stacked mode), the same section keeps its Section wrapper and an un-chromeless table", async () => {
+  test("without hideTitle (stacked mode), the same section keeps its Section wrapper and an un-chromeless, unbounded-height table", async () => {
     const { dispatcher } = stubDispatcher();
     let capturedChromeless: boolean | undefined;
+    let capturedScrollBody: boolean | undefined;
     const capturingDataTable: ComponentType<DataTableProps> = (props) => {
       capturedChromeless = props.chromeless;
+      capturedScrollBody = props.scrollBody;
       return testDataTable(props);
     };
     render(
@@ -229,6 +237,7 @@ describe("RelatedListSection — tabs-mode card chrome (fw#2722)", () => {
     await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
     expect(rtlScreen.getByTestId(`related-list-${historySection.title}`)).toBeTruthy();
     expect(capturedChromeless).toBeUndefined();
+    expect(capturedScrollBody).toBeUndefined();
   });
 });
 
@@ -378,4 +387,254 @@ describe("RelatedListSection — rowActions drawer-kind (fw#2710)", () => {
     await waitFor(() => expect(rtlScreen.getByTestId("row-item-7")).toBeTruthy());
     expect(rtlScreen.queryByTestId("action-adjust-rent-item-7")).toBeNull();
   });
+
+  test("a dropped drawer rowAction without onOpenDrawer logs a dev warning naming the action id (fw#2733)", async () => {
+    const { dispatcher } = stubDispatcher([{ id: "item-7", name: "Rent 2024", amount: 1200 }]);
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      renderRelatedList(dispatcher, {
+        kind: "relatedList",
+        title: "Positions",
+        query: "lease:query:items:list",
+        columns: [{ field: "name" }],
+        rowActions: [
+          {
+            kind: "drawer",
+            id: "adjust-rent-warn-only-2733",
+            label: "actions.adjustRent",
+            screen: "adjust-rent-form",
+          },
+        ],
+      });
+
+      await waitFor(() => expect(rtlScreen.getByTestId("row-item-7")).toBeTruthy());
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy.mock.calls[0]?.[0]).toContain("adjust-rent-warn-only-2733");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("a drawer rowAction with onOpenDrawer wired renders without a dev warning (fw#2733)", async () => {
+    const { dispatcher } = stubDispatcher([{ id: "item-7", name: "Rent 2024", amount: 1200 }]);
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      render(
+        <LocaleProvider
+          resolver={createStaticLocaleResolver({ locale: "en-US" })}
+          fallbackBundles={[kumikoDefaultTranslations]}
+        >
+          <DispatcherProvider dispatcher={dispatcher}>
+            <PrimitivesProvider value={testPrimitives()}>
+              <NavProvider value={stubNav().nav}>
+                <RelatedListSection
+                  section={{
+                    kind: "relatedList",
+                    title: "Positions",
+                    query: "lease:query:items:list",
+                    columns: [{ field: "name" }],
+                    rowActions: [
+                      {
+                        kind: "drawer",
+                        id: "adjust-rent-warn-wired-2733",
+                        label: "actions.adjustRent",
+                        screen: "adjust-rent-form",
+                      },
+                    ],
+                  }}
+                  parentId="order-1"
+                  featureName="orders"
+                  onOpenDrawer={noop}
+                />
+              </NavProvider>
+            </PrimitivesProvider>
+          </DispatcherProvider>
+        </LocaleProvider>,
+      );
+
+      await waitFor(() => expect(rtlScreen.getByTestId("row-item-7")).toBeTruthy());
+      expect(rtlScreen.getByTestId("action-adjust-rent-warn-wired-2733-item-7")).toBeTruthy();
+      expect(warnSpy).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
+
+// A DataTable stub that renders one row per query row (DOM order == passed
+// `rows` order, so a re-sort is observable as a re-ordered row list) plus a
+// button that calls `onSortChange` the same way a real SortableHeader click
+// would — enough to prove RelatedListSection actually re-orders rows, not
+// just that a header is clickable.
+const orderedDataTable: ComponentType<DataTableProps> = ({ rows, onSortChange }) => (
+  <div>
+    <table>
+      <tbody>
+        {rows.map((row) => (
+          <tr key={row.id} data-testid={`row-${row.id}`} />
+        ))}
+      </tbody>
+    </table>
+    {onSortChange !== undefined && (
+      <button
+        type="button"
+        data-testid="sort-amount-desc"
+        onClick={() => onSortChange({ field: "amount", dir: "desc" })}
+      >
+        sort
+      </button>
+    )}
+  </div>
+);
+
+function renderedRowOrder(): string[] {
+  return rtlScreen
+    .getAllByTestId(/^row-/)
+    .map((el) => el.getAttribute("data-testid")?.replace("row-", "") ?? "");
+}
+
+describe("RelatedListSection — sorting (fw#2722)", () => {
+  const unsortedRows = [
+    { id: "r1", name: "Charlie", amount: 300 },
+    { id: "r2", name: "Alice", amount: 100 },
+    { id: "r3", name: "Bob", amount: 200 },
+  ];
+
+  test("defaultSort sorts the already-loaded rows client-side, independent of query response order", async () => {
+    const { dispatcher } = stubDispatcher(unsortedRows);
+    render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en-US" })}
+        fallbackBundles={[kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={dispatcher}>
+          <PrimitivesProvider value={{ ...testPrimitives(), DataTable: orderedDataTable }}>
+            <NavProvider value={stubNav().nav}>
+              <RelatedListSection
+                section={{
+                  kind: "relatedList",
+                  title: "Positions",
+                  query: "lease:query:items:list",
+                  columns: [{ field: "amount", sortable: true }],
+                  defaultSort: { field: "amount", dir: "asc" },
+                }}
+                parentId="order-1"
+                featureName="orders"
+              />
+            </NavProvider>
+          </PrimitivesProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(renderedRowOrder()).toEqual(["r2", "r3", "r1"]);
+  });
+
+  test("toggling sort via onSortChange re-orders rows without a refetch", async () => {
+    const { dispatcher, queryCount } = stubDispatcher(unsortedRows);
+    render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en-US" })}
+        fallbackBundles={[kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={dispatcher}>
+          <PrimitivesProvider value={{ ...testPrimitives(), DataTable: orderedDataTable }}>
+            <NavProvider value={stubNav().nav}>
+              <RelatedListSection
+                section={{
+                  kind: "relatedList",
+                  title: "Positions",
+                  query: "lease:query:items:list",
+                  columns: [{ field: "amount", sortable: true }],
+                }}
+                parentId="order-1"
+                featureName="orders"
+              />
+            </NavProvider>
+          </PrimitivesProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(renderedRowOrder()).toEqual(["r1", "r2", "r3"]);
+
+    fireEvent.click(rtlScreen.getByTestId("sort-amount-desc"));
+
+    await waitFor(() => expect(renderedRowOrder()).toEqual(["r1", "r3", "r2"]));
+    expect(queryCount()).toBe(1);
+  });
+
+  test("a section without defaultSort renders rows in the original query order (unchanged behavior)", async () => {
+    const { dispatcher } = stubDispatcher(unsortedRows);
+    render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en-US" })}
+        fallbackBundles={[kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={dispatcher}>
+          <PrimitivesProvider value={{ ...testPrimitives(), DataTable: orderedDataTable }}>
+            <NavProvider value={stubNav().nav}>
+              <RelatedListSection
+                section={{
+                  kind: "relatedList",
+                  title: "Positions",
+                  query: "lease:query:items:list",
+                  columns: [{ field: "amount" }],
+                }}
+                parentId="order-1"
+                featureName="orders"
+              />
+            </NavProvider>
+          </PrimitivesProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(renderedRowOrder()).toEqual(["r1", "r2", "r3"]);
+  });
+});
+
+describe("RelatedListSection — truncation banner (fw#2722 review)", () => {
+  test("nextCursor !== null renders a truncation banner", async () => {
+    const { dispatcher } = stubDispatcher([{ id: "r1", name: "Alice" }], "cursor-abc");
+    renderRelatedList(dispatcher);
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    const banner = rtlScreen.getByTestId("related-list-truncated");
+    expect(banner).toBeTruthy();
+    // Proves {count} actually interpolates (single-brace, the renderer's own
+    // i18n.tsx interpolate() syntax) rather than rendering as literal braces.
+    expect(banner.textContent).toContain("Showing the first 1 entries.");
+  });
+
+  test("nextCursor === null renders no truncation banner", async () => {
+    const { dispatcher } = stubDispatcher([{ id: "r1", name: "Alice" }], null);
+    renderRelatedList(dispatcher);
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.queryByTestId("related-list-truncated")).toBeNull();
+  });
+
+  test("the banner shows regardless of an active sort — an unsorted truncated list is equally misleading", async () => {
+    const { dispatcher } = stubDispatcher(
+      [
+        { id: "r1", name: "Charlie", amount: 300 },
+        { id: "r2", name: "Alice", amount: 100 },
+      ],
+      "cursor-abc",
+    );
+    renderRelatedList(dispatcher, {
+      kind: "relatedList",
+      title: "Positions",
+      query: "lease:query:items:list",
+      columns: [{ field: "amount", sortable: true }],
+      defaultSort: { field: "amount", dir: "asc" },
+    });
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.getByTestId("related-list-truncated")).toBeTruthy();
+  });
 });

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

@@ -10,7 +10,7 @@ import type {
   ListRowViewModel,
   Translate,
 } from "@cosmicdrift/kumiko-headless";
-import { type ReactNode, useMemo } from "react";
+import { type ReactNode, useMemo, useState } from "react";
 import { useNav } from "../app/nav";
 import {
   buildProjectionRowActions,
@@ -19,9 +19,11 @@ import {
 } from "../app/row-actions";
 import { dispatcherErrorText } from "../app/write-failed-error";
 import { useOptionalDispatcher } from "../context/dispatcher-context";
+import type { ListSort } from "../hooks/use-list-url-state";
 import { useQuery } from "../hooks/use-query";
 import { useTranslation } from "../i18n";
 import { usePrimitives } from "../primitives";
+import { sortByAccessor } from "../sort-by-accessor";
 import { RenderList } from "./render-list";
 
 const RELATED_LIST_PSEUDO_ENTITY = "__related-list__";
@@ -36,14 +38,16 @@ type PagedRows = {
 };
 
 // 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).
+// projection-list-shim's synthesizeProjectionEntity, but sortable is read
+// per-column (ListColumnSpec.sortable) instead of screen-wide, since a
+// relatedList section has no single Zod schema to derive it from.
 function synthesizeRelatedListEntity(
   columns: EditRelatedListSectionViewModel["columns"],
 ): EntityDefinition {
-  const fields: Record<string, { type: "text" }> = {};
+  const fields: Record<string, { type: "text"; sortable: boolean }> = {};
   for (const col of columns) {
-    fields[normalizeListColumn(col).field] = { type: "text" };
+    const normalized = normalizeListColumn(col);
+    fields[normalized.field] = { type: "text", sortable: normalized.sortable === true };
   }
   return { fields } as unknown as EntityDefinition;
 }
@@ -69,7 +73,7 @@ export function RelatedListSection({
     initialValues: Readonly<Record<string, unknown>> | undefined,
   ) => void;
 }): ReactNode {
-  const { Banner, Section } = usePrimitives();
+  const { Banner, Section, FillContainer } = usePrimitives();
   const t = useTranslation();
   const effectiveTranslate = translate ?? t;
   const nav = useNav();
@@ -100,6 +104,28 @@ export function RelatedListSection({
 
   const rowsQuery = useQuery<PagedRows>(section.query, payload);
 
+  // Sorted client-side over the already-loaded rows — this section has no
+  // pager (see `payload` above: a one-shot fetch, no cursor/offset), so the
+  // loaded set already IS the full display set and there is no "other page"
+  // a client-side sort could misleadingly hide (fw#2722).
+  const [sort, setSort] = useState<ListSort | null>(section.defaultSort ?? null);
+  const sortAccessors = useMemo(() => {
+    const accessors: Record<string, (row: Readonly<Record<string, unknown>>) => string | number> =
+      {};
+    for (const col of section.columns) {
+      const field = normalizeListColumn(col).field;
+      accessors[field] = (row) => {
+        const value = row[field];
+        return typeof value === "number" ? value : String(value ?? "");
+      };
+    }
+    return accessors;
+  }, [section.columns]);
+  const sortedRows = useMemo(
+    () => sortByAccessor(rowsQuery.data?.rows ?? [], sort, sortAccessors),
+    [rowsQuery.data, sort, sortAccessors],
+  );
+
   const rowClick = section.rowClick;
   // A row-body click target comes from EITHER the legacy `rowClick` field OR
   // a `rowActions` entry marked rowClick:true — the boot-validator rejects
@@ -136,6 +162,14 @@ export function RelatedListSection({
   );
   const rowActionMode = rowActionModeFor(rowActions);
 
+  // A truncated fetch means `sortedRows` is a sort of a partial set, not of
+  // the full related-row set — the client-side sort above (or even plain
+  // unsorted display) would silently claim "these are the top N" when they
+  // are really just "the first N in the server's own order" (fw#2722 review).
+  // `nextCursor` is exactly how the paged envelope marks that: non-null means
+  // more rows exist server-side beyond what was fetched.
+  const truncated = rowsQuery.data !== null && rowsQuery.data.nextCursor !== null;
+
   const content =
     rowsQuery.loading && rowsQuery.data === null ? (
       <Banner padded variant="loading" testId="related-list-loading">
@@ -146,24 +180,47 @@ export function RelatedListSection({
         {dispatcherErrorText(rowsQuery.error, effectiveTranslate)}
       </Banner>
     ) : (
-      <RenderList
-        screen={listScreen}
-        entity={entity}
-        rows={rowsQuery.data?.rows ?? []}
-        featureName={featureName}
-        translate={effectiveTranslate}
-        {...(onRowClick !== undefined && { onRowClick })}
-        {...(rowActions !== undefined && { rowActions })}
-        {...(rowActionMode !== undefined && { rowActionMode })}
-        {...(hideTitle === true && { chromeless: true })}
-      />
+      <>
+        {truncated && (
+          <Banner variant="info" testId="related-list-truncated">
+            {effectiveTranslate("kumiko.list.related-list-truncated", {
+              count: sortedRows.length,
+            })}
+          </Banner>
+        )}
+        <RenderList
+          screen={listScreen}
+          entity={entity}
+          rows={sortedRows}
+          featureName={featureName}
+          translate={effectiveTranslate}
+          sort={sort}
+          onSortChange={setSort}
+          {...(onRowClick !== undefined && { onRowClick })}
+          {...(rowActions !== undefined && { rowActions })}
+          {...(rowActionMode !== undefined && { rowActionMode })}
+          {...(hideTitle === true && { chromeless: true, scrollBody: true })}
+        />
+      </>
     );
 
   // hideTitle (tabs mode) → the tab panel is already the boundary: no
-  // Section card wrapper here, and `chromeless` above drops the table's own
-  // card frame too (fw#2722) — the list sits directly in the tab. Stacked
-  // (non-tabs) sections keep both cards since they render a visible title.
-  if (hideTitle) return content;
+  // Section card wrapper here, `chromeless` above drops the table's own
+  // card frame too, and `scrollBody` fills this wrapper's height so a long
+  // Akte tab scrolls internally instead of stretching the page (fw#2722) —
+  // the list sits directly in the tab. `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
+  // primitive (not a raw `<div>`) because `renderer` stays DOM-free —
+  // `Section`/`Card` were rejected for this spot in favor of a dedicated
+  // chromeless primitive; see `FillContainerProps` in primitives.tsx.
+  // 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.
+  if (hideTitle) {
+    return FillContainer !== undefined ? <FillContainer>{content}</FillContainer> : content;
+  }
 
   return (
     <Section title={section.title} testId={`related-list-${section.title}`}>

package/src/components/render-edit.tsx

@@ -628,6 +628,15 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // true when editable fields exist or an extension opted into composed submit (fw#2359).
   const isFormEditable = hasEditableSection(filteredSections);
 
+  // A lone relatedList tab (hideSectionTitles is only ever set by the tabs
+  // layout, which also narrows filteredSections to that one active section)
+  // needs its own tab panel to fill the available height so its table
+  // scrolls inside the panel instead of the whole page stretching to the
+  // row count (fw#2722). Any other layout — multiple sections, a non-
+  // relatedList tab, stacked (non-tabs) forms — keeps normal document-flow
+  // height untouched.
+  const fillHeight = hideSectionTitles === true && filteredSections[0]?.kind === "relatedList";
+
   // Persistiert alle composed Extension-Sections mit der aufgelösten entityId.
   // false = eine Section schlug fehl (ihr i18n-Key landet im Banner). Ohne
   // Entity-Kontext (create-mode ohne route-id) gibt es nichts zu schreiben.
@@ -1077,6 +1086,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
         stickyActions={isWizard}
         {...(screen.layout.width !== undefined && { width: screen.layout.width })}
         {...(headerRegion !== undefined && { headerRegion })}
+        {...(fillHeight && { fillHeight })}
       >
         {draftCandidates !== null && (
           <Banner

package/src/components/render-list.tsx

@@ -114,6 +114,10 @@ export type RenderListProps = {
    *  frame for a host that already provides one (relatedList in a tabs-mode
    *  section, fw#2722). Default false. */
   readonly chromeless?: boolean;
+  /** Forwarded to `DataTableProps.scrollBody` — bounds the table height and
+   *  scrolls rows internally instead of growing the page (relatedList in a
+   *  tabs-mode section, fw#2722). Default false. */
+  readonly scrollBody?: boolean;
 };
 
 // Resolved-Form einer Toolbar-Action: KumikoScreen baut das aus dem
@@ -163,6 +167,7 @@ export function RenderList(props: RenderListProps): ReactNode {
     onFilterChange,
     onFilterReset,
     chromeless,
+    scrollBody,
   } = props;
   // Wie RenderEdit: Translate-Fallback aus dem i18next-Context, sonst
   // wären Column-Header raw i18n-Keys.
@@ -378,6 +383,7 @@ export function RenderList(props: RenderListProps): ReactNode {
         {...(onFilterChange !== undefined && { onFilterChange })}
         {...(onFilterReset !== undefined && { onFilterReset })}
         {...(chromeless !== undefined && { chromeless })}
+        {...(scrollBody !== undefined && { scrollBody })}
         testId="render-list-table"
       />
     </>

package/src/i18n-defaults.ts

@@ -64,6 +64,8 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.list.end-of-list": "— End of list —",
     "kumiko.list.sort.label": "Sort",
     "kumiko.list.sort.unsorted": "Unsorted",
+    "kumiko.list.related-list-truncated":
+      "Showing the first {count} entries. More are available but not loaded — this list does not paginate.",
     "kumiko.reference.system-tenant": "System",
 
     "kumiko.pager.status": "{from}–{to} of {total}",

package/src/index.ts

@@ -184,6 +184,7 @@ export type {
   EmbeddedListInputProps,
   EmbeddedListTotal,
   FieldProps,
+  FillContainerProps,
   FormProps,
   FormWidth,
   GridCellProps,

package/src/primitives.tsx

@@ -623,6 +623,15 @@ export type DataTableProps = {
    *  and would otherwise show a card nested inside that boundary. Default
    *  false: unchanged card-framed table. */
   readonly chromeless?: boolean;
+  /** Fills the available height of its flex container and scrolls rows
+   *  internally instead of growing with row count — for a host that would
+   *  otherwise have a long table stretch the whole page, or a short table
+   *  leave dead space below it (a tab panel, fw#2722). Requires the same
+   *  flex-fill chain FormProps.fillHeight sets up above it; without that
+   *  ancestor chain this collapses to zero height (Web: `flex-1 min-h-0`
+   *  has no effect outside a sized flex-col ancestor). Default false:
+   *  unchanged document-flow table that grows with its content. */
+  readonly scrollBody?: boolean;
 };
 
 // ---- EmbeddedListInput (createEmbeddedListField widget) ----
@@ -755,6 +764,14 @@ export type FormProps = {
    *  instead of rendering as unpadded siblings before it. Native impls may
    *  ignore this prop. */
   readonly headerRegion?: ReactNode;
+  /** Sizes the form to fill its container's height (instead of the page's
+   *  natural content height) so a single scrolling child — a lone
+   *  relatedList tab's table — can scroll internally instead of stretching
+   *  the whole page (fw#2722). Only set by RenderEdit for a lone relatedList
+   *  tab section; every other caller leaves it unset and keeps normal
+   *  document-flow height. Native impls may ignore this prop (already a
+   *  bounded viewport there). */
+  readonly fillHeight?: boolean;
 };
 
 /** Titled Gruppe von Feldern. Web: `<fieldset>` + `<legend>`, Native:
@@ -784,6 +801,21 @@ export type SectionProps = {
   readonly icon?: IconKey;
 };
 
+/** Chromeless flex-fill layout host — no title, no card frame, no padding,
+ *  just a container that sizes to fill its parent and lets one scrolling
+ *  child scroll internally instead of the page growing (fw#2722). Web:
+ *  `<div className="flex flex-1 min-h-0 flex-col">`. Native: Views are
+ *  already flex-column and the parent is already a bounded viewport there,
+ *  so a native impl may render this as a bare Fragment. Used only as the
+ *  terminal link in `RenderEdit`'s `fillHeight` chain (`RelatedListSection`'s
+ *  `hideTitle` branch) — `Section`/`Card` were rejected here because both
+ *  carry title/padding/border chrome this spot doesn't want and would double
+ *  up with the table's own padding. */
+export type FillContainerProps = {
+  readonly children: ReactNode;
+  readonly testId?: string;
+};
+
 /** Columns-basiertes Layout. Web: CSS grid, Native: Flex-Wrap mit
  *  Width-%, oder react-native-grid. Jedes direkte Child kann eine
  *  `GridCell`-Wrapping bekommen für span-Kontrolle.
@@ -1139,6 +1171,10 @@ export type CorePrimitives = {
    *  CorePrimitives mocks in tests keep compiling — additive rollout of
    *  a new primitive shouldn't force every test double to grow a stub. */
   readonly JsonView?: ComponentType<JsonViewProps>;
+  /** Optional (unlike the other Core-Primitives) so existing partial
+   *  CorePrimitives mocks in tests keep compiling — additive rollout of
+   *  a new primitive shouldn't force every test double to grow a stub. */
+  readonly FillContainer?: ComponentType<FillContainerProps>;
 };
 
 /** Offene Extension-Zone für App-eigene Primitives. Devs erweitern