@cosmicdrift/kumiko-renderer 0.250.0 → 0.252.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.250.0",
+  "version": "0.252.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.250.0",
-    "@cosmicdrift/kumiko-headless": "0.250.0",
+    "@cosmicdrift/kumiko-framework": "0.252.0",
+    "@cosmicdrift/kumiko-headless": "0.252.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.250.0"
+    "@cosmicdrift/kumiko-locale-de": "0.252.0"
   },
   "repository": {
     "type": "git",

package/src/app/__tests__/entity-list-screen-padding.test.tsx

@@ -0,0 +1,111 @@
+// A list screen's chrome is the DataTable's own outer wrapper — no
+// FormScreenShell/PageSection sits around it. `screenPadding` is how that
+// wrapper reaches the shared screen-padding token, so it has to be set on the
+// real list path (KumikoScreen → EntityListScreen → EntityListBody →
+// RenderList), not just be available on the primitive (fw#2640).
+import { describe, expect, test } from "bun:test";
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { render, waitFor } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { type CorePrimitives, type DataTableProps, PrimitivesProvider } from "../../primitives";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import { NavProvider } from "../nav";
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+function stubDispatcher(): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async () => ({
+      isSuccess: true,
+      data: { rows: [], total: 0 },
+    })) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function buildSchema(): FeatureSchema {
+  const entity: EntityDefinition = {
+    fields: {
+      name: { type: "text", maxLength: 200, required: false, searchable: false, sortable: false },
+    },
+  };
+  const listScreen: EntityListScreenDefinition = {
+    id: "org-list",
+    type: "entityList",
+    entity: "org",
+    columns: ["name"],
+  };
+  return {
+    featureName: "orgs",
+    entities: { org: entity },
+    screens: [listScreen],
+  } as FeatureSchema;
+}
+
+describe("entityList screen padding (fw#2640)", () => {
+  test("the list screen marks its table as the screen body", async () => {
+    let capturedScreenPadding: boolean | undefined;
+    const capturingDataTable: ComponentType<DataTableProps> = (props) => {
+      capturedScreenPadding = props.screenPadding;
+      return null;
+    };
+    const primitives: CorePrimitives = {
+      Button: noop,
+      Banner: passChildren,
+      Field: passChildren,
+      Input: noop,
+      DataTable: capturingDataTable,
+      Form: passChildren,
+      Section: passChildren,
+      Card: passChildren,
+      Grid: passChildren,
+      GridCell: passChildren,
+      Text: passChildren,
+      Heading: noop,
+      Dialog: noop,
+      Modal: noop,
+      Lightbox: noop,
+      ConfigSourceBadge: noop,
+      ConfigCascadeView: noop,
+      Link: noop,
+    };
+    render(
+      <LocaleProvider resolver={createStaticLocaleResolver({ locale: "de-DE" })}>
+        <DispatcherProvider dispatcher={stubDispatcher()}>
+          <NavProvider
+            value={{
+              route: { screenId: "orgs:org-list" },
+              navigate: () => {},
+              replace: () => {},
+              hrefFor: () => "",
+              searchParams: {},
+              setSearchParams: () => {},
+            }}
+          >
+            <PrimitivesProvider value={primitives}>
+              <KumikoScreen schema={buildSchema()} qn="orgs:screen:org-list" />
+            </PrimitivesProvider>
+          </NavProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    await waitFor(() => expect(capturedScreenPadding).toBe(true));
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -6,7 +6,6 @@ import type {
   EntityDefinition,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
-  ListFacetSpec,
   ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
   RowAction,
@@ -50,6 +49,12 @@ import { useDashboardBody } from "./dashboard-body";
 import type { FeatureSchema } from "./feature-schema";
 import { buildFormSchema } from "./form-schema";
 import { layoutFieldNames } from "./layout-fields";
+import {
+  buildFilterFacets,
+  buildFilterPayload,
+  type ResolvedFacetSpec,
+  resolveProjectionFacetSpecs,
+} from "./list-facets";
 import { useNav } from "./nav";
 import {
   synthesizeProjectionDetailEntity,
@@ -1066,58 +1071,6 @@ export function buildListQueryPayload(state: {
   return payload;
 }
 
-// One resolved facet, independent of where the type info came from — an
-// entity field (entityList) or an explicit ListFacetSpec (projectionList,
-// fw#2224). Shared by buildFilterFacets/buildFilterPayload below so both
-// screen types build their query-payload filters and DataTable facet-UI
-// through the same code, instead of two copies that can drift.
-type ResolvedFacetSpec = {
-  readonly field: string;
-  readonly type: "select" | "boolean";
-  readonly label: string;
-  readonly options: readonly { readonly value: string; readonly label: string }[];
-};
-
-function buildFilterFacets(specs: readonly ResolvedFacetSpec[]): DataTableFacet[] {
-  return specs.map((spec) => ({ field: spec.field, label: spec.label, options: spec.options }));
-}
-
-// User-selected faceted filters from URL-state → payload.filters. Boolean
-// fields coerce "true"/"false" strings to real booleans (DB column is
-// boolean); everything else stays string[] under op:"in" (multi-select
-// semantics). `typeOf` resolves a field to its known type string —
-// undefined means "unknown field", so it's dropped (typo-safe: a stale/
-// hand-crafted URL param for an undeclared field never reaches the
-// server). Deliberately NOT gated on the field being a *facet* — entityList
-// passes through any field present in entity.fields, matching its
-// pre-fw#2224 behavior; only the boolean-coercion branch cares about type.
-
-function isFacetI18nKey(label: string): boolean {
-  return !/\s/.test(label) && (label.includes(".") || label.includes(":"));
-}
-
-function buildFilterPayload(
-  urlFilters: Readonly<Record<string, readonly string[]>>,
-  typeOf: (field: string) => string | undefined,
-): { field: string; op: "in"; value: unknown }[] {
-  const out: { field: string; op: "in"; value: unknown }[] = [];
-  for (const [field, values] of Object.entries(urlFilters)) {
-    if (values.length === 0) continue;
-    // `id` is a base column (not a declared facet), allowed as an id-set
-    // filter so a header-slot control — e.g. the tags TagFilter — can narrow
-    // ANY list to a resolved set of row ids without the host declaring a facet.
-    if (field === "id") {
-      out.push({ field, op: "in", value: values });
-      continue;
-    }
-    const type = typeOf(field);
-    if (type === undefined) continue;
-    const value = type === "boolean" ? values.map((v) => v === "true") : values;
-    out.push({ field, op: "in", value });
-  }
-  return out;
-}
-
 // entityList adapter — one DataTableFacet per filterable select/boolean
 // entity field, labels via the standard field/option i18n convention.
 function resolveEntityFacetSpecs(
@@ -1164,39 +1117,6 @@ function resolveEntityFacetSpecs(
   return out;
 }
 
-// projectionList adapter — a projectionList has no entity/i18n convention to
-// derive labels from, so ListFacetSpec carries every label explicitly
-// (fw#2224). Labels may be raw display strings or i18n keys; run them
-// through translate like entity facets (passthrough when the key is missing).
-function resolveProjectionFacetSpecs(
-  facets: readonly ListFacetSpec[] | undefined,
-  translate: Translate,
-): ResolvedFacetSpec[] {
-  if (facets === undefined) return [];
-  const tr = (label: string): string => (isFacetI18nKey(label) ? translate(label) : label);
-  return facets.map((facet) =>
-    facet.type === "select"
-      ? {
-          field: facet.field,
-          type: "select",
-          label: tr(facet.label),
-          options: facet.options.map((opt) => ({
-            value: opt.value,
-            label: tr(opt.label),
-          })),
-        }
-      : {
-          field: facet.field,
-          type: "boolean",
-          label: tr(facet.label),
-          options: [
-            { value: "true", label: tr(facet.trueLabel) },
-            { value: "false", label: tr(facet.falseLabel) },
-          ],
-        },
-  );
-}
-
 // ---- drawer-kind actions: ToolbarAction (fw#2225) + RowAction (fw#2710) ----
 //
 // Shared across EntityListBody, ProjectionListBody, ProjectionDetailBody and
@@ -1841,6 +1761,7 @@ function EntityListBody({
         onSearchChange={urlState.setQ}
         sort={effectiveSort}
         onSortChange={urlState.setSort}
+        screenPadding
         {...(pager !== undefined && { pager })}
         {...(rowActions !== undefined && { rowActions })}
         {...(rowActionMode !== undefined && { rowActionMode })}
@@ -2131,6 +2052,7 @@ function ProjectionListBody({
         onSearchChange={urlState.setQ}
         sort={activeSort}
         onSortChange={urlState.setSort}
+        screenPadding
         {...(pager !== undefined && { pager })}
         {...(rowActions !== undefined && { rowActions })}
         {...(rowActionMode !== undefined && { rowActionMode })}

package/src/app/list-facets.ts

@@ -0,0 +1,90 @@
+// Split from kumiko-screen.tsx: related-list-section.tsx renders through
+// kumiko-screen.tsx, so importing this back from there would be a require cycle.
+import type { ListFacetSpec } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Translate } from "@cosmicdrift/kumiko-headless";
+import type { DataTableFacet } from "../primitives";
+
+// One resolved facet, independent of where the type info came from — an
+// entity field (entityList) or an explicit ListFacetSpec (projectionList,
+// fw#2224). Shared by buildFilterFacets/buildFilterPayload below so both
+// screen types build their query-payload filters and DataTable facet-UI
+// through the same code, instead of two copies that can drift.
+export type ResolvedFacetSpec = {
+  readonly field: string;
+  readonly type: "select" | "boolean";
+  readonly label: string;
+  readonly options: readonly { readonly value: string; readonly label: string }[];
+};
+
+export function buildFilterFacets(specs: readonly ResolvedFacetSpec[]): DataTableFacet[] {
+  return specs.map((spec) => ({ field: spec.field, label: spec.label, options: spec.options }));
+}
+
+// User-selected faceted filters from URL-state → payload.filters. Boolean
+// fields coerce "true"/"false" strings to real booleans (DB column is
+// boolean); everything else stays string[] under op:"in" (multi-select
+// semantics). `typeOf` resolves a field to its known type string —
+// undefined means "unknown field", so it's dropped (typo-safe: a stale/
+// hand-crafted URL param for an undeclared field never reaches the
+// server). Deliberately NOT gated on the field being a *facet* — entityList
+// passes through any field present in entity.fields, matching its
+// pre-fw#2224 behavior; only the boolean-coercion branch cares about type.
+
+function isFacetI18nKey(label: string): boolean {
+  return !/\s/.test(label) && (label.includes(".") || label.includes(":"));
+}
+
+export function buildFilterPayload(
+  urlFilters: Readonly<Record<string, readonly string[]>>,
+  typeOf: (field: string) => string | undefined,
+): { field: string; op: "in"; value: unknown }[] {
+  const out: { field: string; op: "in"; value: unknown }[] = [];
+  for (const [field, values] of Object.entries(urlFilters)) {
+    if (values.length === 0) continue;
+    // `id` is a base column (not a declared facet), allowed as an id-set
+    // filter so a header-slot control — e.g. the tags TagFilter — can narrow
+    // ANY list to a resolved set of row ids without the host declaring a facet.
+    if (field === "id") {
+      out.push({ field, op: "in", value: values });
+      continue;
+    }
+    const type = typeOf(field);
+    if (type === undefined) continue;
+    const value = type === "boolean" ? values.map((v) => v === "true") : values;
+    out.push({ field, op: "in", value });
+  }
+  return out;
+}
+
+// projectionList adapter — a projectionList has no entity/i18n convention to
+// derive labels from, so ListFacetSpec carries every label explicitly
+// (fw#2224). Labels may be raw display strings or i18n keys; run them
+// through translate like entity facets (passthrough when the key is missing).
+export function resolveProjectionFacetSpecs(
+  facets: readonly ListFacetSpec[] | undefined,
+  translate: Translate,
+): ResolvedFacetSpec[] {
+  if (facets === undefined) return [];
+  const tr = (label: string): string => (isFacetI18nKey(label) ? translate(label) : label);
+  return facets.map((facet) =>
+    facet.type === "select"
+      ? {
+          field: facet.field,
+          type: "select",
+          label: tr(facet.label),
+          options: facet.options.map((opt) => ({
+            value: opt.value,
+            label: tr(opt.label),
+          })),
+        }
+      : {
+          field: facet.field,
+          type: "boolean",
+          label: tr(facet.label),
+          options: [
+            { value: "true", label: tr(facet.trueLabel) },
+            { value: "false", label: tr(facet.falseLabel) },
+          ],
+        },
+  );
+}

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

@@ -10,6 +10,7 @@ import { kumikoDefaultTranslations } from "../../i18n-defaults";
 import {
   type CorePrimitives,
   type DataTableProps,
+  type InputProps,
   PrimitivesProvider,
   type SectionProps,
 } from "../../primitives";
@@ -54,6 +55,15 @@ const testDataTable: ComponentType<DataTableProps> = ({ rows, rowActions }) => (
   </table>
 );
 
+const testInput = (props: InputProps) =>
+  props.kind === "text" ? (
+    <input
+      data-testid={props.id}
+      value={props.value}
+      onChange={(e) => props.onChange(e.target.value)}
+    />
+  ) : null;
+
 function testPrimitives(): CorePrimitives {
   return {
     Button: noop,
@@ -61,7 +71,7 @@ function testPrimitives(): CorePrimitives {
       <div data-testid={testId}>{children}</div>
     ),
     Field: passChildren,
-    Input: noop,
+    Input: testInput,
     DataTable: testDataTable,
     Form: noop,
     Section: testSection,
@@ -638,3 +648,293 @@ describe("RelatedListSection — truncation banner (fw#2722 review)", () => {
     expect(rtlScreen.getByTestId("related-list-truncated")).toBeTruthy();
   });
 });
+
+// A DataTable stub that renders the toolbarStart slot (carries the search
+// Input) and filterFacets as one button per option, wired straight to
+// onFilterChange/onFilterReset — enough to prove RelatedListSection resolves
+// facets and wires search through RenderList, without the production
+// DataTable's own facet-dropdown chrome.
+const searchFacetDataTable: ComponentType<DataTableProps> = ({
+  rows,
+  toolbarStart,
+  filterFacets,
+  onFilterChange,
+  onFilterReset,
+}) => (
+  <div>
+    {toolbarStart}
+    {(filterFacets ?? []).map((facet) => (
+      <div key={facet.field}>
+        {facet.options.map((opt) => (
+          <button
+            key={opt.value}
+            type="button"
+            data-testid={`facet-${facet.field}-${opt.value}`}
+            onClick={() => onFilterChange?.(facet.field, [opt.value])}
+          >
+            {opt.label}
+          </button>
+        ))}
+      </div>
+    ))}
+    {onFilterReset !== undefined && (
+      <button type="button" data-testid="filter-reset" onClick={onFilterReset}>
+        Reset
+      </button>
+    )}
+    <table>
+      <tbody>
+        {rows.map((row) => (
+          <tr key={row.id} data-testid={`row-${row.id}`} />
+        ))}
+      </tbody>
+    </table>
+  </div>
+);
+
+// A dispatcher stub that genuinely filters a fixed row set by the received
+// payload — `search` as a case-insensitive substring on `name`, `filters`
+// entries (`{ field, op: "in", value }`) as membership on that field —
+// instead of returning canned rows, so a test can tell a real payload from a
+// stale one. Every payload it sees is recorded for the "last payload"
+// assertions below.
+function filteringDispatcher(rows: readonly Record<string, unknown>[]): {
+  dispatcher: Dispatcher;
+  payloads: Record<string, unknown>[];
+} {
+  const payloads: Record<string, unknown>[] = [];
+  const dispatcher: Dispatcher = {
+    write: (async () => ({ isSuccess: true, data: null })) as Dispatcher["write"],
+    query: (async (_type: string, payload: unknown) => {
+      const p = payload as {
+        search?: string;
+        filters?: readonly { field: string; op: "in"; value: readonly unknown[] }[];
+      };
+      payloads.push(p);
+      let result = rows;
+      if (p.search !== undefined && p.search !== "") {
+        const term = p.search.toLowerCase();
+        result = result.filter((r) =>
+          String(r["name"] ?? "")
+            .toLowerCase()
+            .includes(term),
+        );
+      }
+      for (const f of p.filters ?? []) {
+        result = result.filter((r) => f.value.includes(r[f.field]));
+      }
+      return { isSuccess: true, data: { rows: result, nextCursor: null } };
+    }) as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+  return { dispatcher, payloads };
+}
+
+function renderWithDataTable(
+  dispatcher: Dispatcher,
+  section: EditRelatedListSectionViewModel,
+  DataTable: ComponentType<DataTableProps>,
+  hideTitle?: boolean,
+) {
+  return render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en-US" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={dispatcher}>
+        <PrimitivesProvider value={{ ...testPrimitives(), DataTable }}>
+          <NavProvider value={stubNav().nav}>
+            <RelatedListSection
+              section={section}
+              parentId="order-1"
+              featureName="orders"
+              {...(hideTitle === true && { hideTitle: true })}
+            />
+          </NavProvider>
+        </PrimitivesProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("RelatedListSection — search + facets (fw#2740)", () => {
+  const nameRows = [
+    { id: "r1", name: "Alice" },
+    { id: "r2", name: "Bob" },
+  ];
+
+  test("searchable: true — typing (after the 300ms debounce) sends payload.search and narrows the rendered rows", async () => {
+    const { dispatcher, payloads } = filteringDispatcher(nameRows);
+    renderWithDataTable(
+      dispatcher,
+      {
+        kind: "relatedList",
+        title: "Contacts",
+        query: "lease:query:contacts:list",
+        columns: [{ field: "name" }],
+        searchable: true,
+      },
+      searchFacetDataTable,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.getByTestId("row-r2")).toBeTruthy();
+
+    fireEvent.change(rtlScreen.getByTestId("render-list-search"), {
+      target: { value: "ali" },
+    });
+
+    await waitFor(
+      () => {
+        const last = payloads[payloads.length - 1];
+        expect(last?.["search"]).toBe("ali");
+      },
+      { timeout: 2000 },
+    );
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.queryByTestId("row-r2")).toBeNull();
+  });
+
+  test("without searchable, RenderList shows no search input and no payload ever carries a search key", async () => {
+    const { dispatcher, payloads } = filteringDispatcher(nameRows);
+    renderWithDataTable(
+      dispatcher,
+      {
+        kind: "relatedList",
+        title: "Contacts",
+        query: "lease:query:contacts:list",
+        columns: [{ field: "name" }],
+      },
+      searchFacetDataTable,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.queryByTestId("render-list-search")).toBeNull();
+    for (const p of payloads) {
+      expect("search" in p).toBe(false);
+    }
+  });
+
+  test("tabs mode (hideTitle): the search box still renders and narrows the rows", async () => {
+    const { dispatcher, payloads } = filteringDispatcher(nameRows);
+    renderWithDataTable(
+      dispatcher,
+      {
+        kind: "relatedList",
+        title: "Contacts",
+        query: "lease:query:contacts:list",
+        columns: [{ field: "name" }],
+        searchable: true,
+      },
+      searchFacetDataTable,
+      true,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.getByTestId("row-r2")).toBeTruthy();
+    expect(rtlScreen.getByTestId("render-list-search")).toBeTruthy();
+
+    fireEvent.change(rtlScreen.getByTestId("render-list-search"), {
+      target: { value: "ali" },
+    });
+
+    await waitFor(
+      () => {
+        const last = payloads[payloads.length - 1];
+        expect(last?.["search"]).toBe("ali");
+      },
+      { timeout: 2000 },
+    );
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.queryByTestId("row-r2")).toBeNull();
+  });
+
+  const statusSection: EditRelatedListSectionViewModel = {
+    kind: "relatedList",
+    title: "Positions",
+    query: "lease:query:items:list",
+    columns: [{ field: "name" }, { field: "status" }],
+    facets: [
+      {
+        field: "status",
+        type: "select",
+        label: "Status",
+        options: [
+          { value: "active", label: "Active" },
+          { value: "ended", label: "Ended" },
+        ],
+      },
+    ],
+  };
+  const statusRows = [
+    { id: "active-1", name: "Running", status: "active" },
+    { id: "ended-1", name: "Closed", status: "ended" },
+  ];
+
+  test("select facet: clicking an option filters payload.filters and rows, resetting clears both", async () => {
+    const { dispatcher, payloads } = filteringDispatcher(statusRows);
+    renderWithDataTable(dispatcher, statusSection, searchFacetDataTable);
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-active-1")).toBeTruthy());
+    expect(rtlScreen.getByTestId("row-ended-1")).toBeTruthy();
+
+    fireEvent.click(rtlScreen.getByTestId("facet-status-active"));
+
+    await waitFor(() => expect(rtlScreen.queryByTestId("row-ended-1")).toBeNull());
+    expect(rtlScreen.getByTestId("row-active-1")).toBeTruthy();
+    expect(payloads[payloads.length - 1]?.["filters"]).toEqual([
+      { field: "status", op: "in", value: ["active"] },
+    ]);
+
+    fireEvent.click(rtlScreen.getByTestId("filter-reset"));
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-ended-1")).toBeTruthy());
+    expect(rtlScreen.getByTestId("row-active-1")).toBeTruthy();
+    expect(payloads[payloads.length - 1]?.["filters"]).toBeUndefined();
+  });
+
+  test("boolean facet: selecting a value sends a real boolean in payload.filters and narrows rows accordingly", async () => {
+    const paidRows = [
+      { id: "paid-1", name: "Invoice A", paid: true },
+      { id: "unpaid-1", name: "Invoice B", paid: false },
+    ];
+    const { dispatcher, payloads } = filteringDispatcher(paidRows);
+    renderWithDataTable(
+      dispatcher,
+      {
+        kind: "relatedList",
+        title: "Invoices",
+        query: "lease:query:invoices:list",
+        columns: [{ field: "name" }, { field: "paid" }],
+        facets: [
+          {
+            field: "paid",
+            type: "boolean",
+            label: "Paid",
+            trueLabel: "Yes",
+            falseLabel: "No",
+          },
+        ],
+      },
+      searchFacetDataTable,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-paid-1")).toBeTruthy());
+    expect(rtlScreen.getByTestId("row-unpaid-1")).toBeTruthy();
+
+    fireEvent.click(rtlScreen.getByTestId("facet-paid-true"));
+
+    await waitFor(() => expect(rtlScreen.queryByTestId("row-unpaid-1")).toBeNull());
+    expect(rtlScreen.getByTestId("row-paid-1")).toBeTruthy();
+    expect(payloads[payloads.length - 1]?.["filters"]).toEqual([
+      { field: "paid", op: "in", value: [true] },
+    ]);
+  });
+});

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

@@ -10,7 +10,12 @@ import type {
   ListRowViewModel,
   Translate,
 } from "@cosmicdrift/kumiko-headless";
-import { type ReactNode, useMemo, useState } from "react";
+import { type ReactNode, useCallback, useMemo, useState } from "react";
+import {
+  buildFilterFacets,
+  buildFilterPayload,
+  resolveProjectionFacetSpecs,
+} from "../app/list-facets";
 import { useNav } from "../app/nav";
 import {
   buildProjectionRowActions,
@@ -22,7 +27,7 @@ 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 { type DataTableFacet, usePrimitives } from "../primitives";
 import { sortByAccessor } from "../sort-by-accessor";
 import { RenderList } from "./render-list";
 
@@ -94,16 +99,53 @@ export function RelatedListSection({
     [section.columns],
   );
 
+  // Local state, not URL state: a section `id` is optional, so there is no
+  // stable URL key to namespace against — the section's sort is local for the
+  // same reason. Consequence: search/filters reset on reload.
+  const [search, setSearch] = useState("");
+  const [filters, setFilters] = useState<Readonly<Record<string, readonly string[]>>>({});
+
+  const facetSpecs = useMemo(
+    () => resolveProjectionFacetSpecs(section.facets, effectiveTranslate),
+    [section.facets, effectiveTranslate],
+  );
+  const filterPayload = useMemo(
+    () =>
+      buildFilterPayload(filters, (field) => facetSpecs.find((spec) => spec.field === field)?.type),
+    [filters, facetSpecs],
+  );
+  const filterFacets = useMemo<DataTableFacet[]>(() => buildFilterFacets(facetSpecs), [facetSpecs]);
+
   const payload = useMemo(
     () => ({
       [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
+      // doesn't accept would 422 the whole section.
+      ...(section.searchable === true && search !== "" && { search }),
+      ...(section.facets !== undefined && filterPayload.length > 0 && { filters: filterPayload }),
     }),
-    [section.parentParam, section.pageSize, parentId],
+    [
+      section.parentParam,
+      section.pageSize,
+      section.searchable,
+      section.facets,
+      parentId,
+      search,
+      filterPayload,
+    ],
   );
 
   const rowsQuery = useQuery<PagedRows>(section.query, payload);
 
+  const onFilterChange = useCallback(
+    (field: string, values: readonly string[]) =>
+      setFilters((prev) => ({ ...prev, [field]: values })),
+    [],
+  );
+  const onFilterReset = useCallback(() => setFilters({}), []);
+
   // 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"
@@ -196,6 +238,17 @@ export function RelatedListSection({
           translate={effectiveTranslate}
           sort={sort}
           onSortChange={setSort}
+          {...(section.searchable === true && {
+            searchable: true,
+            searchValue: search,
+            onSearchChange: setSearch,
+          })}
+          {...(filterFacets.length > 0 && {
+            filterFacets,
+            filterValues: filters,
+            onFilterChange,
+            onFilterReset,
+          })}
           {...(onRowClick !== undefined && { onRowClick })}
           {...(rowActions !== undefined && { rowActions })}
           {...(rowActionMode !== undefined && { rowActionMode })}
@@ -206,9 +259,11 @@ export function RelatedListSection({
 
   // 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` 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
+  // 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
   // 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

package/src/components/render-edit.tsx

@@ -631,11 +631,12 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
 
   // 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
+  // needs its own tab panel capped at 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.
+  // row count (fw#2722) — a short table still sizes to its content instead
+  // of stretching the panel to the bottom (fw#2778). 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.

package/src/components/render-list.tsx

@@ -118,6 +118,11 @@ export type RenderListProps = {
    *  scrolls rows internally instead of growing the page (relatedList in a
    *  tabs-mode section, fw#2722). Default false. */
   readonly scrollBody?: boolean;
+  /** Forwarded to `DataTableProps.screenPadding` — the table carries the
+   *  shared screen padding because it is the screen body (entityList/
+   *  projectionList, fw#2640). Not set for an embedded relatedList.
+   *  Default false. */
+  readonly screenPadding?: boolean;
 };
 
 // Resolved-Form einer Toolbar-Action: KumikoScreen baut das aus dem
@@ -172,6 +177,7 @@ export function RenderList(props: RenderListProps): ReactNode {
     onFilterReset,
     chromeless,
     scrollBody,
+    screenPadding,
   } = props;
   // Wie RenderEdit: Translate-Fallback aus dem i18next-Context, sonst
   // wären Column-Header raw i18n-Keys.
@@ -388,6 +394,7 @@ export function RenderList(props: RenderListProps): ReactNode {
         {...(onFilterReset !== undefined && { onFilterReset })}
         {...(chromeless !== undefined && { chromeless })}
         {...(scrollBody !== undefined && { scrollBody })}
+        {...(screenPadding !== undefined && { screenPadding })}
         testId="render-list-table"
       />
     </>

package/src/primitives.tsx

@@ -637,6 +637,14 @@ export type DataTableProps = {
    *  has no effect outside a sized flex-col ancestor). Default false:
    *  unchanged document-flow table that grows with its content. */
   readonly scrollBody?: boolean;
+  /** Uses the shared screen padding (wider bottom inset) instead of the
+   *  table's symmetric embedded inset — for a table that IS the screen body
+   *  (entityList/projectionList), so a list screen ends at the same footer
+   *  distance as a form or custom screen (fw#2640). Hosts set this or
+   *  `scrollBody`, not both: the wider bottom inset competes with
+   *  `scrollBody`'s flex-fill height budget.
+   *  Default false: unchanged symmetric inset for an embedded table. */
+  readonly screenPadding?: boolean;
 };
 
 // ---- EmbeddedListInput (createEmbeddedListField widget) ----
@@ -807,9 +815,10 @@ export type SectionProps = {
 };
 
 /** 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
+ *  just a container that sizes to its content and, once the ancestor chain
+ *  is height-constrained, shrinks so one scrolling child can scroll
+ *  internally instead of the page growing (fw#2722, height fw#2778). Web:
+ *  `<div className="flex 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