@cosmicdrift/kumiko-renderer-web 0.245.0 → 0.247.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.245.0",
+  "version": "0.247.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -16,9 +16,9 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.245.0",
-    "@cosmicdrift/kumiko-headless": "0.245.0",
-    "@cosmicdrift/kumiko-renderer": "0.245.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.247.0",
+    "@cosmicdrift/kumiko-headless": "0.247.0",
+    "@cosmicdrift/kumiko-renderer": "0.247.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
@@ -64,7 +64,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "tailwindcss": "^4.3.0",
-    "@cosmicdrift/kumiko-locale-de": "0.245.0"
+    "@cosmicdrift/kumiko-locale-de": "0.247.0"
   },
   "repository": {
     "type": "git",

package/src/__tests__/nav-tree.test.tsx

@@ -21,8 +21,8 @@ import type {
   TreeChildrenSubscribe,
   TreeNode,
 } from "@cosmicdrift/kumiko-framework/engine";
-import type { FeatureSchema, LiveEventSubscriber } from "@cosmicdrift/kumiko-renderer";
-import { LiveEventsProvider } from "@cosmicdrift/kumiko-renderer";
+import type { FeatureSchema, LiveEventSubscriber, NavApi } from "@cosmicdrift/kumiko-renderer";
+import { LiveEventsProvider, NavProvider } from "@cosmicdrift/kumiko-renderer";
 import { act } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { NavProvidersProvider } from "../app/nav-providers-context";
@@ -463,6 +463,90 @@ describe("NavTree navBadges (Runtime-Badge-Slot)", () => {
   });
 });
 
+// fw#2724: leaving a list for a sub-screen (entityEdit/actionForm/...) used
+// to lose BOTH orientation cues at once — nav marks nothing, breadcrumb
+// shrinks to one crumb. NavTree now falls back to resolveParentScreenId
+// (same resolution shell-breadcrumb.ts uses) when the routed screen has no
+// node of its own in the tree.
+function navWithRoute(screenId: string): NavApi {
+  return {
+    route: { screenId },
+    navigate: () => {},
+    replace: () => {},
+    hrefFor: () => "",
+    searchParams: {},
+    setSearchParams: () => {},
+  };
+}
+
+describe("NavTree active-marker parent fallback", () => {
+  test("screen without its own nav entry highlights the resolved parent, without aria-current", () => {
+    const schema: FeatureSchema = {
+      featureName: "showcase",
+      entities: {},
+      screens: [
+        { id: "user-list", type: "entityList", entity: "profile", columns: [] },
+        {
+          id: "user-edit",
+          type: "entityEdit",
+          // Deliberately a DIFFERENT entity than "user-list" — the old
+          // same-entity heuristic must NOT be what resolves this; only the
+          // explicit listScreenId does.
+          entity: "user-detail",
+          listScreenId: "user-list",
+          layout: { sections: [{ fields: [] }] },
+        },
+      ],
+      navs: [{ id: "user-list", label: "Users", screen: "user-list", order: 10 }],
+    } as FeatureSchema;
+
+    render(
+      <NavProvider value={navWithRoute("user-edit")}>
+        <NavTree schema={schema} />
+      </NavProvider>,
+    );
+
+    const link = screen.getByText("Users").closest("a");
+    expect(link?.getAttribute("data-active")).toBe("true");
+    expect(link?.hasAttribute("aria-current")).toBe(false);
+  });
+
+  test("screen with its own nav entry still marks itself and keeps aria-current=page", () => {
+    const schema: FeatureSchema = {
+      featureName: "showcase",
+      entities: {},
+      screens: [
+        { id: "user-list", type: "entityList", entity: "profile", columns: [] },
+        {
+          id: "user-edit",
+          type: "entityEdit",
+          entity: "profile",
+          layout: { sections: [{ fields: [] }] },
+        },
+      ],
+      navs: [
+        { id: "user-list", label: "Users", screen: "user-list", order: 10 },
+        { id: "user-edit", label: "Edit User", screen: "user-edit", order: 20 },
+      ],
+    } as FeatureSchema;
+
+    render(
+      <NavProvider value={navWithRoute("user-edit")}>
+        <NavTree schema={schema} />
+      </NavProvider>,
+    );
+
+    const editLink = screen.getByText("Edit User").closest("a");
+    expect(editLink?.getAttribute("data-active")).toBe("true");
+    expect(editLink?.getAttribute("aria-current")).toBe("page");
+
+    // The list is not silently highlighted too — only the exact match is.
+    const listLink = screen.getByText("Users").closest("a");
+    expect(listLink?.getAttribute("data-active")).toBe("false");
+    expect(listLink?.hasAttribute("aria-current")).toBe(false);
+  });
+});
+
 // ── Visual-Tree-Merge: dynamische Knoten in der EINEN Nav ──────────────
 //
 // Beweist die vier Caps die NavTree aus dem alten VisualTree übernimmt:

package/src/__tests__/primitives.test.tsx

@@ -437,6 +437,71 @@ describe("DataTable", () => {
     expect(onRowClick).toHaveBeenCalledWith(row);
   });
 
+  // chromeless (fw#2722): a relatedList section in a tabs-mode Akte already
+  // sits inside a tab panel — the table's own card frame would nest a card
+  // inside that boundary without separating anything further.
+  describe("chromeless", () => {
+    const cols = [{ field: "name", label: "Name", type: "string", sortable: false }] as const;
+    const oneRow = [{ id: "r1", values: { name: "Alice" } }];
+
+    // Table itself renders its own [data-slot="table-container"] wrapper div
+    // (ui/table.tsx) around the <table data-testid> — the card frame lives
+    // one level up, on DefaultDataTable's own wrapping div.
+    test("default: table renders with its own card frame", () => {
+      render(<DataTable columns={cols} rows={oneRow} testId="t" />);
+      const wrapper = screen.getByTestId("t").parentElement?.parentElement;
+      expect(wrapper?.className).toContain("border");
+      expect(wrapper?.className).toContain("rounded-lg");
+      expect(wrapper?.className).toContain("bg-card");
+    });
+
+    test("chromeless: table drops the card frame, table markup is unchanged", () => {
+      render(<DataTable columns={cols} rows={oneRow} testId="t" chromeless />);
+      const wrapper = screen.getByTestId("t").parentElement?.parentElement;
+      expect(wrapper?.className).not.toContain("border");
+      expect(wrapper?.className).not.toContain("rounded-lg");
+      expect(wrapper?.className).not.toContain("bg-card");
+      expect(screen.getByTestId("row-r1")).not.toBeNull();
+    });
+  });
+
+  // scrollBody (fw#2722): a relatedList section in a tabs-mode Akte must not
+  // stretch the whole page with a long list, or leave dead space below a
+  // short one — bounds the table to a fixed height and scrolls rows inside
+  // it, regardless of how many rows there are.
+  describe("scrollBody", () => {
+    const cols = [{ field: "name", label: "Name", type: "string", sortable: false }] as const;
+    const shortRows = [{ id: "r1", values: { name: "Alice" } }];
+    const longRows = Array.from({ length: 50 }, (_, i) => ({
+      id: `r${i}`,
+      values: { name: `Row ${i}` },
+    }));
+
+    test("default: table has no fixed height and grows with its content", () => {
+      render(<DataTable columns={cols} rows={longRows} testId="t" />);
+      const wrapper = screen.getByTestId("t").parentElement?.parentElement;
+      expect(wrapper?.className).not.toContain("overflow-y-auto");
+      expect(wrapper?.className).toContain("overflow-hidden");
+    });
+
+    test("scrollBody: a long list fills its flex container and scrolls internally", () => {
+      render(<DataTable columns={cols} rows={longRows} testId="t" scrollBody />);
+      const wrapper = screen.getByTestId("t").parentElement?.parentElement;
+      expect(wrapper?.className).toContain("overflow-y-auto");
+      expect(wrapper?.className).toContain("flex-1");
+      expect(wrapper?.className).toContain("min-h-0");
+      expect(screen.getAllByTestId(/^row-/)).toHaveLength(50);
+    });
+
+    test("scrollBody: a short list gets the same flex-fill treatment (fills space instead of shrinking)", () => {
+      render(<DataTable columns={cols} rows={shortRows} testId="t" scrollBody />);
+      const wrapper = screen.getByTestId("t").parentElement?.parentElement;
+      expect(wrapper?.className).toContain("overflow-y-auto");
+      expect(wrapper?.className).toContain("flex-1");
+      expect(wrapper?.className).toContain("min-h-0");
+    });
+  });
+
   // Sort-Header pinnt das 3-State-Toggle-Verhalten + Visual-Indicator
   // + aria-sort. Renderer-Vertrag mit dem Caller (RenderList): jede
   // sortable-Column liefert beim Click den nächsten Sort-State zurück
@@ -1450,6 +1515,37 @@ describe("Form", () => {
     const contentContainer = footer.previousElementSibling as HTMLElement;
     expect(contentContainer.className).not.toContain("max-sm:pb-32");
   });
+
+  // fillHeight (fw#2722): the flex-fill chain RenderEdit opts a lone
+  // relatedList tab into, so its table can scroll inside the tab panel
+  // instead of the whole page stretching to the row count.
+  test("fillHeight: form root and its content container size to h-full/flex-1 min-h-0", () => {
+    render(
+      <Form onSubmit={() => undefined} testId="form" fillHeight>
+        <div>content</div>
+      </Form>,
+    );
+    const form = screen.getByTestId("form");
+    expect(form.className).toContain("h-full");
+    expect(form.className).toContain("min-h-0");
+    // form > FormScreenShell > card(overflow-hidden) — the card is the
+    // flex-1 min-h-0 child that claims the remaining height below headerRegion.
+    const card = form.firstElementChild?.firstElementChild as HTMLElement;
+    expect(card.className).toContain("flex-1");
+    expect(card.className).toContain("min-h-0");
+  });
+
+  test("without fillHeight: form root keeps its normal, content-sized height", () => {
+    render(
+      <Form onSubmit={() => undefined} testId="form">
+        <div>content</div>
+      </Form>,
+    );
+    const form = screen.getByTestId("form");
+    expect(form.className).not.toContain("h-full");
+    const card = form.firstElementChild?.firstElementChild as HTMLElement;
+    expect(card.className).not.toContain("flex-1");
+  });
 });
 
 describe("Banner padded", () => {

package/src/__tests__/projection-detail.test.tsx

@@ -923,3 +923,143 @@ describe("KumikoScreen / projectionDetail extension section with its own <form>
     expect(outerSubmitFired).toBe(false);
   });
 });
+
+// fw#2713: `actions` are on the record the head shows, not on whichever tab
+// is open — they used to render in the card footer, below the active tab's
+// content, so a long tab pushed them off-screen and they visually "moved"
+// as the tab content's length changed. They now render inside the head
+// region (title/status/metrics), before any tab content, in both layout
+// modes — `single` gets the same treatment as `tabs` since the actions
+// belong to the header regardless of how the body is laid out.
+describe("KumikoScreen / projectionDetail header actions placement (fw#2713)", () => {
+  const dispatcher: Dispatcher = createMockDispatcher({
+    query: (async () => ({
+      isSuccess: true,
+      data: { userId: "user-42", createdAt: "2026-07-01T00:00:00Z" },
+    })) as unknown as Dispatcher["query"],
+  });
+
+  test("with actions declared: the action button renders in the head region, before the tab content, not in the form footer", async () => {
+    const screenWithActions: ProjectionDetailScreenDefinition = {
+      ...detailScreen,
+      header: { title: "userId" },
+      layout: { mode: "tabs", sections: detailScreen.layout.sections },
+      actions: [
+        {
+          kind: "navigate",
+          id: "open-user",
+          label: "sessions.detail.action.openUser",
+          screen: "user-detail",
+        },
+      ],
+    };
+    const schemaWithActions: FeatureSchema = {
+      featureName: "sessions",
+      entities: {},
+      screens: [screenWithActions],
+    };
+
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen
+          schema={schemaWithActions}
+          qn="sessions:screen:session-detail"
+          entityId="sess-1"
+        />
+      </DispatcherProvider>,
+    );
+
+    const actionButton = await waitFor(() => screen.getByTestId("render-edit-action-open-user"));
+    // The footer regions RenderEdit's Form would otherwise draw the action
+    // into are gone entirely — the action moved out, it didn't just gain a
+    // second home.
+    expect(screen.queryByTestId("render-edit-form-actions")).toBeNull();
+    expect(screen.queryByTestId("render-edit-form-actions-secondary")).toBeNull();
+    // The action sits in the head Card, ahead of the field it shares a
+    // screen with in document order — i.e. inside headerRegion, not the
+    // card body below it.
+    const field = screen.getByTestId("field-userId");
+    expect(
+      actionButton.compareDocumentPosition(field) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  test("without actions: no action area renders at all (no empty strip, no leftover footer)", async () => {
+    render(
+      <DispatcherProvider dispatcher={dispatcher}>
+        <KumikoScreen schema={schema} qn="sessions:screen:session-detail" entityId="sess-1" />
+      </DispatcherProvider>,
+    );
+
+    await waitFor(() => screen.getByTestId("render-edit-form"));
+    expect(screen.queryByTestId("kumiko-screen-projection-detail-actions")).toBeNull();
+    expect(screen.queryByTestId("render-edit-form-actions")).toBeNull();
+    expect(screen.queryByTestId("render-edit-form-actions-secondary")).toBeNull();
+  });
+
+  test("switching tabs leaves the action in place — same head placement regardless of which tab is active", async () => {
+    const tabsScreen: ProjectionDetailScreenDefinition = {
+      ...detailScreen,
+      header: { title: "userId" },
+      layout: {
+        mode: "tabs",
+        sections: [
+          { id: "overview", title: "Session", fields: ["userId"] },
+          { id: "meta", title: "Meta", fields: ["createdAt"] },
+        ],
+      },
+      actions: [
+        {
+          kind: "navigate",
+          id: "open-user",
+          label: "sessions.detail.action.openUser",
+          screen: "user-detail",
+        },
+      ],
+    };
+    const tabsSchema: FeatureSchema = {
+      featureName: "sessions",
+      entities: {},
+      screens: [tabsScreen],
+    };
+    function navWithTab(tab: string | undefined): NavApi {
+      return {
+        route: undefined,
+        navigate: () => {},
+        replace: () => {},
+        hrefFor: () => "",
+        searchParams: tab !== undefined ? { tab } : {},
+        setSearchParams: () => {},
+      };
+    }
+
+    const { unmount } = render(
+      <NavProvider value={navWithTab("overview")}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <KumikoScreen schema={tabsSchema} qn="sessions:screen:session-detail" entityId="sess-1" />
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+    const buttonOnOverview = await waitFor(() =>
+      screen.getByTestId("render-edit-action-open-user"),
+    );
+    expect(buttonOnOverview.textContent).toBe("sessions.detail.action.openUser");
+    unmount();
+
+    render(
+      <NavProvider value={navWithTab("meta")}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <KumikoScreen schema={tabsSchema} qn="sessions:screen:session-detail" entityId="sess-1" />
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+    const buttonOnMeta = await waitFor(() => screen.getByTestId("render-edit-action-open-user"));
+    expect(buttonOnMeta.textContent).toBe("sessions.detail.action.openUser");
+    // Same head placement on both tabs — ahead of whichever field the
+    // active tab shows, not trailing it.
+    const fieldOnMeta = screen.getByTestId("field-createdAt");
+    expect(
+      buttonOnMeta.compareDocumentPosition(fieldOnMeta) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+});

package/src/layout/__tests__/shell-breadcrumb.test.ts

@@ -105,4 +105,78 @@ describe("resolveDetailBreadcrumb", () => {
   test("unknown screen returns undefined", () => {
     expect(resolveDetailBreadcrumb([], "missing", t)).toBeUndefined();
   });
+
+  // fw#2724: explicit `listScreenId` on entityEdit/actionForm must win over
+  // the rowAction/entity heuristics, not just supplement them (the way it
+  // already did for custom/projectionDetail above).
+  test("explicit listScreenId on entityEdit wins over the rowAction heuristic", () => {
+    const screens: ScreenDefinition[] = [
+      {
+        id: "user-list",
+        type: "entityList",
+        entity: "user",
+        columns: ["email"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "view",
+            label: "kumiko.actions.view",
+            screen: "user-edit",
+            entityId: "id",
+          },
+        ],
+      },
+      {
+        id: "user-archive",
+        type: "entityList",
+        entity: "user",
+        columns: ["email"],
+        rowActions: [],
+      },
+      {
+        id: "user-edit",
+        type: "entityEdit",
+        entity: "user",
+        listScreenId: "user-archive",
+        layout: { sections: [{ fields: ["email"] }] },
+      },
+    ];
+    // Without the explicit field, the rowAction heuristic would resolve
+    // "user-list" (see "entityList navigate rowAction..." above) — the
+    // declared listScreenId overrides that guess.
+    expect(resolveDetailBreadcrumb(screens, "user-edit", t)?.[0]?.screenId).toBe("user-archive");
+  });
+
+  // Regression guard: an actionForm without listScreenId (the common case —
+  // the field is new and optional) must keep resolving exactly like before,
+  // via the rowAction heuristic. Pins that existing apps see no change.
+  test("actionForm without listScreenId still resolves via the rowAction heuristic", () => {
+    const screens: ScreenDefinition[] = [
+      {
+        id: "invoice-list",
+        type: "entityList",
+        entity: "invoice",
+        columns: ["status"],
+        rowActions: [
+          {
+            kind: "navigate",
+            id: "approve",
+            label: "kumiko.actions.view",
+            screen: "invoice-approve",
+            entityId: "id",
+          },
+        ],
+      },
+      {
+        id: "invoice-approve",
+        type: "actionForm",
+        handler: "billing:write:invoice:approve",
+        fields: { notes: { type: "text" } },
+        layout: { sections: [{ fields: ["notes"] }] },
+      },
+    ];
+    expect(resolveDetailBreadcrumb(screens, "invoice-approve", t)?.[0]?.screenId).toBe(
+      "invoice-list",
+    );
+  });
 });

package/src/layout/nav-tree.tsx

@@ -56,6 +56,7 @@ import {
   SidebarMenuSubItem,
   useSidebar,
 } from "../ui/sidebar";
+import { resolveParentScreenId } from "./shell-breadcrumb";
 import { useDispatchTarget } from "./target-resolver-stub";
 import { parseTargetFromSearchParams } from "./target-url";
 
@@ -92,6 +93,24 @@ const NavBadgesContext = createContext<ReadonlyMap<string, ReactNode>>(EMPTY_BAD
 type NavFilter = { readonly q: string; readonly matches: (rawLabel: string) => boolean };
 const NavFilterContext = createContext<NavFilter>({ q: "", matches: () => true });
 
+// Which nav node should highlight for the current route. `exact` means the
+// active screen has its own node in {tree} (aria-current="page" belongs
+// here); otherwise {screenId} is the resolved parent from
+// resolveParentScreenId — a screen reachable only through a list stays
+// orientable, but a Screen-Reader shouldn't be told it IS that list.
+type ActiveScreenMarker = { readonly screenId: string; readonly exact: boolean } | undefined;
+const ActiveScreenMarkerContext = createContext<ActiveScreenMarker>(undefined);
+
+// Walks only the static `children` — provider-emitted nodes (treeNodeToNavNode
+// below) never set `screen`, so they can't hide a match this walk would miss.
+function treeContainsScreen(nodes: readonly NavNode[], screenId: string): boolean {
+  return nodes.some(
+    (n) =>
+      (n.screen !== undefined && lastSegment(n.screen) === screenId) ||
+      treeContainsScreen(n.children, screenId),
+  );
+}
+
 // Ein Knoten überlebt den Filter, wenn er selbst oder ein Nachfahre matcht.
 // Provider-Kinder sind zur Filterzeit schon materialisiert (Provider-Knoten
 // sind default-expanded → eager geladen), darum reicht die statische
@@ -115,6 +134,19 @@ export function NavTree({
     return resolveNavigation({ source, ...(user !== undefined && { user }) });
   }, [app, user, allowedNavQns]);
 
+  const nav = useNav();
+  const activeScreenId = nav.route?.screenId;
+  // Same "no nav entry of its own" gap the breadcrumb closes (fw#2724):
+  // when the routed screen has no node in {tree}, fall back to its
+  // resolved parent so a detail/edit/form screen still orients the user.
+  const activeMarker = useMemo((): ActiveScreenMarker => {
+    if (activeScreenId === undefined) return undefined;
+    if (treeContainsScreen(tree, activeScreenId)) return { screenId: activeScreenId, exact: true };
+    const allScreens = app.features.flatMap((f) => f.screens);
+    const parentScreenId = resolveParentScreenId(allScreens, activeScreenId);
+    return parentScreenId !== undefined ? { screenId: parentScreenId, exact: false } : undefined;
+  }, [tree, app.features, activeScreenId]);
+
   // Collapsed-Set: nur die explizit zugeklappten qualified-names. Default
   // ist also "alles auf" — neue Features tauchen sofort offen auf, ohne
   // dass der User erst klicken muss.
@@ -148,34 +180,36 @@ export function NavTree({
   const navFilter = useMemo<NavFilter>(() => ({ q, matches }), [q, matches]);
 
   return (
-    <NavFilterContext.Provider value={navFilter}>
-      <NavBadgesContext.Provider value={navBadges ?? EMPTY_BADGES}>
-        <div data-testid={testId} data-kumiko-layout="nav-tree" className="flex w-full flex-col">
-          <div className="px-2 pt-2 pb-1 group-data-[collapsible=icon]:hidden">
-            <SidebarInput
-              value={filter}
-              onChange={(e) => setFilter(e.target.value)}
-              placeholder={t("kumiko.nav.search")}
-              aria-label={t("kumiko.nav.search")}
-            />
-          </div>
-          {tree.map((node) =>
-            isPureSection(node) ? (
-              <NavSection
-                key={node.qualifiedName}
-                node={node}
-                collapsed={collapsed}
-                onToggle={onToggle}
+    <ActiveScreenMarkerContext.Provider value={activeMarker}>
+      <NavFilterContext.Provider value={navFilter}>
+        <NavBadgesContext.Provider value={navBadges ?? EMPTY_BADGES}>
+          <div data-testid={testId} data-kumiko-layout="nav-tree" className="flex w-full flex-col">
+            <div className="px-2 pt-2 pb-1 group-data-[collapsible=icon]:hidden">
+              <SidebarInput
+                value={filter}
+                onChange={(e) => setFilter(e.target.value)}
+                placeholder={t("kumiko.nav.search")}
+                aria-label={t("kumiko.nav.search")}
               />
-            ) : (
-              <SidebarMenu key={node.qualifiedName} className="px-2 py-1">
-                <NavMenuNode node={node} collapsed={collapsed} onToggle={onToggle} />
-              </SidebarMenu>
-            ),
-          )}
-        </div>
-      </NavBadgesContext.Provider>
-    </NavFilterContext.Provider>
+            </div>
+            {tree.map((node) =>
+              isPureSection(node) ? (
+                <NavSection
+                  key={node.qualifiedName}
+                  node={node}
+                  collapsed={collapsed}
+                  onToggle={onToggle}
+                />
+              ) : (
+                <SidebarMenu key={node.qualifiedName} className="px-2 py-1">
+                  <NavMenuNode node={node} collapsed={collapsed} onToggle={onToggle} />
+                </SidebarMenu>
+              ),
+            )}
+          </div>
+        </NavBadgesContext.Provider>
+      </NavFilterContext.Provider>
+    </ActiveScreenMarkerContext.Provider>
   );
 }
 
@@ -387,6 +421,9 @@ type NavNodeState = {
   readonly expandable: boolean;
   readonly isExpanded: boolean;
   readonly active: boolean;
+  // Narrower than `active`: true only for the node that IS the routed
+  // screen — never for a parent-fallback match. Drives aria-current="page".
+  readonly ariaCurrent: boolean;
   readonly childNodes: readonly NavNode[];
   readonly hidden: boolean;
   readonly providerLoading: boolean;
@@ -416,8 +453,12 @@ function useNavNodeState(node: NavNode, collapsed: ReadonlySet<string>): NavNode
     () => parseTargetFromSearchParams(nav.searchParams),
     [nav.searchParams],
   );
+  const activeMarker = useContext(ActiveScreenMarkerContext);
   const screenActive =
-    node.screen !== undefined && nav.route?.screenId === lastSegment(node.screen);
+    node.screen !== undefined &&
+    activeMarker !== undefined &&
+    lastSegment(node.screen) === activeMarker.screenId;
+  const screenIsExactMatch = screenActive && activeMarker?.exact === true;
   const targetActive = node.target !== undefined && targetsEqual(node.target, activeTarget);
   const childNodes = node.provider === true ? (providerChildren ?? []) : node.children;
   const visibleChildNodes = filterActive
@@ -429,6 +470,7 @@ function useNavNodeState(node: NavNode, collapsed: ReadonlySet<string>): NavNode
     expandable,
     isExpanded,
     active: screenActive || targetActive,
+    ariaCurrent: screenIsExactMatch || targetActive,
     childNodes: visibleChildNodes,
     // Ein gefilterter Knoten verschwindet nur, wenn weder er selbst noch ein
     // sichtbar gebliebenes Kind matcht — sonst bliebe ein leerer Ordner-Header.
@@ -595,7 +637,7 @@ function NavMenuNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
         <SidebarMenuButton asChild isActive={s.active} tooltip={s.displayLabel}>
           <KumikoLink
             to={{ ...(s.workspaceId !== undefined && { workspaceId: s.workspaceId }), screenId }}
-            {...(s.active && { "aria-current": "page" })}
+            {...(s.ariaCurrent && { "aria-current": "page" })}
           >
             <NavLeadingIcon node={node} active={s.active} label={s.displayLabel} />
             <span
@@ -715,7 +757,7 @@ function NavSubNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
         <SidebarMenuSubButton asChild isActive={s.active}>
           <KumikoLink
             to={{ ...(s.workspaceId !== undefined && { workspaceId: s.workspaceId }), screenId }}
-            {...(s.active && { "aria-current": "page" })}
+            {...(s.ariaCurrent && { "aria-current": "page" })}
           >
             <NavLeadingIcon node={node} active={s.active} label={s.displayLabel} />
             <span

package/src/layout/shell-breadcrumb.ts

@@ -1,5 +1,5 @@
 import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
-import { lastSegment } from "./nav-tree";
+import { lastSegment } from "@cosmicdrift/kumiko-renderer";
 
 export type BreadcrumbCrumb = {
   readonly label: string;
@@ -10,13 +10,38 @@ export function screenTitleKey(screenShortId: string): string {
   return `screen:${screenShortId}.title`;
 }
 
-export function resolveDetailBreadcrumb(
+// Every screen type carrying `listScreenId` declares it identically — reading
+// it here (instead of at each call site) keeps the switch the only place
+// that has to grow when a new screen type adopts the field.
+function explicitListScreenId(screen: ScreenDefinition): string | undefined {
+  switch (screen.type) {
+    case "custom":
+    case "projectionDetail":
+    case "entityEdit":
+    case "actionForm":
+      return screen.listScreenId;
+    default:
+      return undefined;
+  }
+}
+
+// Shared by the breadcrumb (this file) and NavTree's active-marker fallback
+// (nav-tree.tsx) — both need "which list screen does this detail belong to",
+// so this is the one place that answers it. An explicit `listScreenId` wins
+// over the heuristics below (rowAction target / same-entity entityList): a
+// screen author who declares it is opting out of the guess.
+function resolveParentScreen(
   screens: readonly ScreenDefinition[],
-  detailScreenId: string,
-  t: (key: string) => string,
-): readonly BreadcrumbCrumb[] | undefined {
-  const detail = screens.find((s) => lastSegment(s.id) === detailScreenId);
-  if (detail === undefined) return undefined;
+  detail: ScreenDefinition,
+): ScreenDefinition | undefined {
+  const detailScreenId = lastSegment(detail.id);
+
+  const listFromExplicit = ((): ScreenDefinition | undefined => {
+    const explicitId = explicitListScreenId(detail);
+    return explicitId !== undefined
+      ? screens.find((s) => lastSegment(s.id) === explicitId)
+      : undefined;
+  })();
 
   const listFromRowAction = screens.find((s) => {
     if (s.type !== "entityList") return false;
@@ -28,22 +53,31 @@ export function resolveDetailBreadcrumb(
       ? screens.find((s) => s.type === "entityList" && s.entity === detail.entity)
       : undefined;
 
-  const listFromCustomParent =
-    detail.type === "custom" && detail.listScreenId !== undefined
-      ? screens.find((s) => lastSegment(s.id) === detail.listScreenId)
-      : undefined;
+  return listFromExplicit ?? listFromRowAction ?? listFromEntity;
+}
 
-  // projectionDetail has no entity to pair with an entityList (unlike
-  // entityEdit above) — `listScreenId` is its only back-navigation source.
-  // Needed because RenderEdit's Cancel button is never wired up for this
-  // screen type and isn't reachable via a listFromRowAction either.
-  const listFromProjectionDetailParent =
-    detail.type === "projectionDetail" && detail.listScreenId !== undefined
-      ? screens.find((s) => lastSegment(s.id) === detail.listScreenId)
-      : undefined;
+/** The short id of {screenId}'s parent list screen, resolved via the same
+ *  logic as `resolveDetailBreadcrumb` — `undefined` when nothing resolves
+ *  (unknown screen, or no explicit/heuristic parent). */
+export function resolveParentScreenId(
+  screens: readonly ScreenDefinition[],
+  screenId: string,
+): string | undefined {
+  const detail = screens.find((s) => lastSegment(s.id) === screenId);
+  if (detail === undefined) return undefined;
+  const parent = resolveParentScreen(screens, detail);
+  return parent !== undefined ? lastSegment(parent.id) : undefined;
+}
+
+export function resolveDetailBreadcrumb(
+  screens: readonly ScreenDefinition[],
+  detailScreenId: string,
+  t: (key: string) => string,
+): readonly BreadcrumbCrumb[] | undefined {
+  const detail = screens.find((s) => lastSegment(s.id) === detailScreenId);
+  if (detail === undefined) return undefined;
 
-  const list =
-    listFromRowAction ?? listFromEntity ?? listFromCustomParent ?? listFromProjectionDetailParent;
+  const list = resolveParentScreen(screens, detail);
   if (list === undefined) {
     return [{ label: t(screenTitleKey(detailScreenId)) }];
   }

package/src/primitives/index.tsx

@@ -25,6 +25,7 @@ import {
   type DataTableFacet,
   type DataTableProps,
   type FieldProps,
+  type FillContainerProps,
   type FormProps,
   type FormWidth,
   type GridCellProps,
@@ -903,6 +904,8 @@ function DefaultDataTable({
   onCellChange,
   getRowTestId,
   getCellTestId,
+  chromeless,
+  scrollBody,
 }: DataTableProps): ReactNode {
   // One locale/translate subscription per table — not per cell (fw#2345).
   // Optional hooks: a bare DataTable outside LocaleProvider must not crash.
@@ -935,7 +938,20 @@ function DefaultDataTable({
       // trägt den bg-muted-Grauton. `bg-card` (statt transparent) → die Liste
       // sitzt auf derselben Card-Fläche wie Forms; auf Themes mit farbigem
       // Page-Background (z.B. Cream) matchen Listen sonst nicht die Cards.
-      <div className="overflow-hidden rounded-lg border bg-card">
+      // `chromeless` drops that frame for a host with its own boundary already (a tab panel, fw#2722).
+      // `scrollBody` fills the remaining height of its flex-col ancestor
+      // (see DefaultForm/FormScreenShell's `fillHeight` and this table's own
+      // outer wrapper below) and scrolls rows internally, instead of
+      // `overflow-hidden` (document-flow height, grows with row count) — for
+      // a host where a long list must not stretch the whole page (a tab
+      // panel, fw#2722). `min-h-0` overrides flex's default min-height:auto,
+      // which would otherwise let this grow past its flex-1 share to fit content.
+      <div
+        className={cn(
+          scrollBody === true ? "flex-1 min-h-0 overflow-y-auto" : "overflow-hidden",
+          chromeless !== true && "rounded-lg border bg-card",
+        )}
+      >
         <Table data-testid={testId}>
           <TableHeader className="bg-muted">
             <TableRow className="hover:bg-transparent">
@@ -1137,7 +1153,10 @@ function DefaultDataTable({
     return (
       <div
         data-testid={testId !== undefined ? `${testId}-cards` : "render-list-cards"}
-        className="flex flex-col gap-3"
+        className={cn(
+          "flex flex-col gap-3",
+          scrollBody === true && "flex-1 min-h-0 overflow-y-auto",
+        )}
       >
         {onSortChange !== undefined && sortableColumns.length > 0 && (
           <select
@@ -1239,7 +1258,7 @@ function DefaultDataTable({
   // der Tabelle im selben Padding-Block — kein separater bg-Bar, kein Screen-
   // Titel (der steht im Breadcrumb der Shell).
   return (
-    <div className="flex flex-col gap-4 p-6 w-full">
+    <div className={cn("flex flex-col gap-4 p-6 w-full", scrollBody === true && "flex-1 min-h-0")}>
       {hasToolbar && (
         <div
           data-testid={testId !== undefined ? `${testId}-toolbar` : "render-list-toolbar"}
@@ -2132,6 +2151,7 @@ function DefaultForm({
   width,
   stickyActions,
   headerRegion,
+  fillHeight,
 }: FormProps): ReactNode {
   // Eingebettet (AuthCard etc.): nacktes <form>, gestapelte Felder mit gap —
   // der Container trägt Card/Titel selbst, sonst Card-in-Card.
@@ -2162,12 +2182,25 @@ function DefaultForm({
   // between each other, muted action footer. Shell width defaults to full
   // (same chrome as lists); pass width to narrow (auth-adjacent / dense).
   return (
-    <FormRoot onSubmit={onSubmit} testId={testId} className="flex flex-col w-full">
-      <FormScreenShell {...(width !== undefined && { maxWidth: width })}>
+    <FormRoot
+      onSubmit={onSubmit}
+      testId={testId}
+      className={cn("flex flex-col w-full", fillHeight === true && "h-full min-h-0")}
+    >
+      <FormScreenShell
+        {...(width !== undefined && { maxWidth: width })}
+        {...(fillHeight === true && { fillHeight: true })}
+      >
         {headerRegion !== undefined && (
           <div className="flex flex-col gap-6 mb-8">{headerRegion}</div>
         )}
-        <div className={cn(cardSurface(), "overflow-hidden")}>
+        <div
+          className={cn(
+            cardSurface(),
+            "overflow-hidden",
+            fillHeight === true && "flex-1 min-h-0 flex flex-col",
+          )}
+        >
           {(title !== undefined || subtitle !== undefined) && (
             <div className={cn(cardHeaderBorder, "px-6 pb-4 pt-5")}>
               {title !== undefined && (
@@ -2201,6 +2234,7 @@ function DefaultForm({
               // safe-area, fw#2528) — widen further if a wizard step's last field
               // ever renders visibly clipped under three or more wrapped rows.
               stickyActions === true && "max-sm:pb-32",
+              fillHeight === true && "flex-1 min-h-0",
             )}
           >
             <InsideFormContext.Provider value={true}>{children}</InsideFormContext.Provider>
@@ -2255,18 +2289,30 @@ export function FormScreenShell({
   className,
   testId,
   maxWidth,
+  fillHeight,
 }: {
   readonly children: ReactNode;
   readonly className?: string;
   readonly testId?: string;
   readonly maxWidth?: FormScreenShellWidth;
+  /** Stacks children in a `h-full` flex column instead of normal document
+   *  flow, so a `flex-1 min-h-0` child can claim the remaining height below
+   *  the others (fw#2722 — DefaultForm's tabs+relatedList case). Default
+   *  false: unchanged, content-sized height. */
+  readonly fillHeight?: boolean;
 }): ReactNode {
   const contextWidth = useContext(ScreenWidthContext);
   const width = maxWidth ?? contextWidth;
   return (
     <div
       data-testid={testId}
-      className={cn(screenPaddingClassName, "w-full", screenWidthClassName[width], className)}
+      className={cn(
+        screenPaddingClassName,
+        "w-full",
+        screenWidthClassName[width],
+        fillHeight === true && "h-full flex flex-col min-h-0",
+        className,
+      )}
     >
       {children}
     </div>
@@ -2374,6 +2420,14 @@ function DefaultSection({
   );
 }
 
+function DefaultFillContainer({ children, testId }: FillContainerProps): ReactNode {
+  return (
+    <div data-testid={testId} className="flex flex-1 min-h-0 flex-col">
+      {children}
+    </div>
+  );
+}
+
 function DefaultGrid({ columns, children, testId, maxRows }: GridProps): ReactNode {
   // "auto": content-sized items in a wrapping row (e.g. a metrics band of
   // self-sized tiles) instead of N equal-width, container-stretched tracks.
@@ -2629,4 +2683,5 @@ export const defaultPrimitives: CorePrimitives = {
   StatusBadge: DefaultStatusBadge,
   Metric: DefaultMetric,
   JsonView: DefaultJsonView,
+  FillContainer: DefaultFillContainer,
 };