@cosmicdrift/kumiko-renderer 0.244.0 → 0.246.0

package/package.json

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

package/src/app/__tests__/action-form-shim.test.ts

@@ -23,4 +23,25 @@ describe("synthesizeActionFormScreen", () => {
     expect(screen.entity).toBe("__action-form__");
     expect(screen.layout).toEqual({ sections: [{ title: "Invite", fields: ["email"] }] });
   });
+
+  test("carries description through so RenderEdit can render it as the form subtitle (fw#2723)", () => {
+    const withDescription = synthesizeActionFormScreen({
+      id: "invite-user",
+      type: "actionForm",
+      description: "Invite a new team member by email.",
+      handler: "users:write:invite-user",
+      layout: { sections: [{ title: "Invite", fields: ["email"] }] },
+      fields: { email: { type: "text" } },
+    });
+    expect(withDescription.description).toBe("Invite a new team member by email.");
+
+    const withoutDescription = synthesizeActionFormScreen({
+      id: "invite-user",
+      type: "actionForm",
+      handler: "users:write:invite-user",
+      layout: { sections: [{ title: "Invite", fields: ["email"] }] },
+      fields: { email: { type: "text" } },
+    });
+    expect("description" in withoutDescription).toBe(false);
+  });
 });

package/src/app/__tests__/entity-list-row-action-entity-target.test.tsx

@@ -292,8 +292,17 @@ const TestButton: ComponentType<ButtonProps> = ({ children, onClick, testId }) =
   </button>
 );
 
-const FormWithActions: ComponentType<FormProps> = ({ children, actions, secondaryActions }) => (
+// headerRegion carries projectionDetail's header actions since fw#2713 — a
+// stub that only forwards children/actions/secondaryActions drops them
+// silently, as this test's own action button did until it grew this slot.
+const FormWithActions: ComponentType<FormProps> = ({
+  children,
+  actions,
+  secondaryActions,
+  headerRegion,
+}) => (
   <>
+    {headerRegion !== undefined && <div data-testid="form-header">{headerRegion}</div>}
     <div data-testid="form-body">{children}</div>
     <div data-testid="form-actions">
       {secondaryActions}

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

@@ -43,13 +43,19 @@ const TestButton: ComponentType<ButtonProps> = ({ children, onClick, testId }) =
   </button>
 );
 
-// Form's `actions`/`secondaryActions` slots carry the header buttons under
-// test — passChildren alone would drop them. Wrapped in distinct testid'd
-// containers so a test can assert a banner rendered as a Form CHILD
-// (formError/actionError region) rather than inside the actions row — the
-// review finding this proves.
-const FormWithActions: ComponentType<FormProps> = ({ children, actions, secondaryActions }) => (
+// Header actions (and their error banner) now render inside ProjectionDetail's
+// own head Card, passed through as `headerRegion` (fw#2713) rather than
+// through Form's `actions`/`secondaryActions` slots — wrapped in a distinct
+// testid'd container so a test can assert both live there, not in the
+// actions/body regions Form itself owns.
+const FormWithActions: ComponentType<FormProps> = ({
+  children,
+  actions,
+  secondaryActions,
+  headerRegion,
+}) => (
   <>
+    {headerRegion !== undefined && <div data-testid="form-header">{headerRegion}</div>}
     <div data-testid="form-body">{children}</div>
     <div data-testid="form-actions">
       {secondaryActions}
@@ -410,7 +416,7 @@ describe("projectionDetail default edit action (fw#2166)", () => {
     expect(navigated).toEqual({ screenId: "rent-edit", entityId: "rent-1" });
   });
 
-  test("a failed writeHandler action shows its error in the shared error region, NOT inside the action button row", async () => {
+  test("a failed writeHandler action shows its error in the head region, alongside the action button, NOT in Form's own actions/body regions (fw#2713)", async () => {
     const schema: FeatureSchema = {
       featureName: "app",
       entities: {},
@@ -441,13 +447,17 @@ describe("projectionDetail default edit action (fw#2166)", () => {
 
     const errorBanner = await waitFor(() => getByTestId("render-edit-action-error"));
     expect(errorBanner.textContent).toBe("archive failed: rent is still active");
-    // The banner must be a Form child (formError-adjacent region), not a
-    // descendant of the actions row — a full-width Banner inside the
-    // `justify-end` button row breaks its layout (fw#2166 review finding 5).
-    expect(errorBanner.closest('[data-testid="form-body"]')).not.toBeNull();
+    // Header actions (and their failure banner) render in the head Card via
+    // `headerRegion` now (fw#2713) — not through Form's own actions/body
+    // slots, so both a tab switch and Form's own footer leave them untouched.
+    expect(errorBanner.closest('[data-testid="form-header"]')).not.toBeNull();
+    expect(errorBanner.closest('[data-testid="form-body"]')).toBeNull();
     expect(errorBanner.closest('[data-testid="form-actions"]')).toBeNull();
     expect(
-      getByTestId("render-edit-action-archive").closest('[data-testid="form-actions"]'),
+      getByTestId("render-edit-action-archive").closest('[data-testid="form-header"]'),
     ).not.toBeNull();
+    expect(
+      getByTestId("render-edit-action-archive").closest('[data-testid="form-actions"]'),
+    ).toBeNull();
   });
 });

package/src/app/__tests__/projection-detail-shim.test.ts

@@ -40,4 +40,23 @@ describe("synthesizeProjectionDetailScreen", () => {
     }
     expect(writeFormSection.fields[0]).toEqual({ field: "note", readOnly: false });
   });
+
+  test("carries description through so RenderEdit can render it as the form subtitle (fw#2723)", () => {
+    const withDescription = synthesizeProjectionDetailScreen({
+      id: "order-detail",
+      type: "projectionDetail",
+      description: "Read-only view of a placed order.",
+      query: "orders:query:order:detail",
+      layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+    });
+    expect(withDescription.description).toBe("Read-only view of a placed order.");
+
+    const withoutDescription = synthesizeProjectionDetailScreen({
+      id: "order-detail",
+      type: "projectionDetail",
+      query: "orders:query:order:detail",
+      layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+    });
+    expect("description" in withoutDescription).toBe(false);
+  });
 });

package/src/app/action-form-shim.ts

@@ -45,6 +45,7 @@ export function synthesizeActionFormScreen(
     type: "entityEdit",
     entity: ACTION_FORM_PSEUDO_ENTITY,
     layout: screen.layout,
+    ...(screen.description !== undefined && { description: screen.description }),
     ...(screen.access !== undefined && { access: screen.access }),
   };
 }

package/src/app/kumiko-screen.tsx

@@ -28,6 +28,7 @@ import { fieldLabelKey, fieldOptionLabelKey } from "@cosmicdrift/kumiko-headless
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { extractCreatedId, extractIdField } from "../components/reference-create-dialog";
 import { RenderEdit, type RenderEditAction } from "../components/render-edit";
+import { RenderEditActionButton } from "../components/render-edit-action-button";
 import { RenderList, type ToolbarActionButton } from "../components/render-list";
 import { useDispatcher, useOptionalDispatcher } from "../context/dispatcher-context";
 import { useUserRoles } from "../context/user-roles-context";
@@ -37,6 +38,7 @@ import { useTranslation } from "../i18n";
 import {
   type DataTableFacet,
   type DataTableRowAction,
+  shouldRenderActionsIconOnly,
   statusToneForValue,
   usePrimitives,
 } from "../primitives";
@@ -2174,7 +2176,7 @@ function ProjectionDetailBody({
   readonly translate?: Translate;
   readonly entityId?: string;
 }): ReactNode {
-  const { Banner, Text, Heading, Grid, GridCell, Card, Tabs, StatusBadge, Metric } =
+  const { Banner, Button, Dialog, Text, Heading, Grid, GridCell, Card, Tabs, StatusBadge, Metric } =
     usePrimitives();
   const t = useTranslation();
   const effectiveTranslate = translate ?? t;
@@ -2229,6 +2231,11 @@ function ProjectionDetailBody({
     setReloadNonce((n) => n + 1);
   }, [detailQuery.refetch]);
 
+  // Header actions render directly via RenderEditActionButton (fw#2713,
+  // headerActions moved out of RenderEdit's footer) — this component owns
+  // the failure-surfacing state RenderEdit used to own for them.
+  const [actionError, setActionError] = useState<string | null>(null);
+
   // Default edit action (fw#2166): resolved cross-feature over ALL mounted
   // features, not just this feature's own schema — detailFor itself is
   // resolved cross-feature by the boot-validator (detail-screens.ts), and
@@ -2455,6 +2462,30 @@ function ProjectionDetailBody({
   const hasHeader = screen.header !== undefined;
   const hasMetrics = screen.metrics !== undefined && screen.metrics.length > 0;
   const hasTabs = isTabsMode && Tabs !== undefined && activeSection !== undefined;
+  // ?? [] rather than threading `headerActions !== undefined` through every
+  // use below — an empty array is a safe no-op for .map/.length/icon-collapse.
+  const headerActionsList = headerActions ?? [];
+  const hasHeaderActions = headerActionsList.length > 0;
+  const headerActionsIconOnly = shouldRenderActionsIconOnly(headerActionsList);
+  // Grouped into the head Card alongside title/status/metrics (fw#2713):
+  // these are actions on the record the head shows, not on whichever tab is
+  // open, so they must stay in place across tab switches instead of
+  // trailing the active tab's content in the card footer.
+  const headerActionsContent = hasHeaderActions && (
+    <Grid columns="auto" testId="kumiko-screen-projection-detail-actions">
+      {headerActionsList.map((action) => (
+        <RenderEditActionButton
+          key={action.id}
+          action={action}
+          iconOnly={headerActionsIconOnly}
+          Button={Button}
+          Dialog={Dialog}
+          onError={setActionError}
+        />
+      ))}
+    </Grid>
+  );
+  const hasHeaderCard = hasHeader || hasMetrics || hasHeaderActions;
   // Rendered as RenderEdit's headerRegion (not as JSX siblings before it) so
   // this shares the same page padding/width as the record's edit card below
   // it, instead of sitting flush against the screen edge (fw record-screen
@@ -2462,7 +2493,7 @@ function ProjectionDetailBody({
   const header = screen.header;
   const headerContent = (
     <>
-      {(hasHeader || hasMetrics) && (
+      {hasHeaderCard && (
         <Card>
           {header !== undefined && (
             <>
@@ -2515,6 +2546,12 @@ function ProjectionDetailBody({
               })}
             </Grid>
           )}
+          {headerActionsContent}
+          {actionError !== null && (
+            <Banner variant="error" testId="render-edit-action-error">
+              {actionError}
+            </Banner>
+          )}
         </Card>
       )}
       {hasTabs && activeSection !== undefined && (
@@ -2542,10 +2579,9 @@ function ProjectionDetailBody({
         customSubmit={async () => ({ isSuccess: true, validationBlocked: false, data: undefined })}
         onReload={reloadDetail}
         onRelatedListDrawerAction={openDrawer}
-        {...(headerActions !== undefined && { actions: headerActions })}
         {...(translate !== undefined && { translate })}
         {...(hasTabs && { hideSectionTitles: true })}
-        {...((hasHeader || hasMetrics || hasTabs) && { headerRegion: headerContent })}
+        {...((hasHeaderCard || hasTabs) && { headerRegion: headerContent })}
         valueDisplay={screen.valueDisplay ?? "text"}
       />
       <DrawerHost

package/src/app/projection-detail-shim.ts

@@ -67,6 +67,7 @@ export function synthesizeProjectionDetailScreen(
     layout: { sections, ...(screen.layout.width !== undefined && { width: screen.layout.width }) },
     allowCreate: false,
     allowDelete: false,
+    ...(screen.description !== undefined && { description: screen.description }),
     ...(screen.fieldLabels !== undefined && { fieldLabels: screen.fieldLabels }),
     ...(screen.slots !== undefined && { slots: screen.slots }),
     ...(screen.access !== undefined && { access: screen.access }),

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

@@ -167,6 +167,71 @@ 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 () => {
+    const { dispatcher } = stubDispatcher();
+    let capturedChromeless: boolean | undefined;
+    const capturingDataTable: ComponentType<DataTableProps> = (props) => {
+      capturedChromeless = props.chromeless;
+      return testDataTable(props);
+    };
+    render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en-US" })}
+        fallbackBundles={[kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={dispatcher}>
+          <PrimitivesProvider value={{ ...testPrimitives(), DataTable: capturingDataTable }}>
+            <NavProvider value={stubNav().nav}>
+              <RelatedListSection
+                section={historySection}
+                parentId="order-1"
+                featureName="orders"
+                hideTitle
+              />
+            </NavProvider>
+          </PrimitivesProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.queryByTestId(`related-list-${historySection.title}`)).toBeNull();
+    expect(capturedChromeless).toBe(true);
+  });
+
+  test("without hideTitle (stacked mode), the same section keeps its Section wrapper and an un-chromeless table", async () => {
+    const { dispatcher } = stubDispatcher();
+    let capturedChromeless: boolean | undefined;
+    const capturingDataTable: ComponentType<DataTableProps> = (props) => {
+      capturedChromeless = props.chromeless;
+      return testDataTable(props);
+    };
+    render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en-US" })}
+        fallbackBundles={[kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={dispatcher}>
+          <PrimitivesProvider value={{ ...testPrimitives(), DataTable: capturingDataTable }}>
+            <NavProvider value={stubNav().nav}>
+              <RelatedListSection
+                section={historySection}
+                parentId="order-1"
+                featureName="orders"
+              />
+            </NavProvider>
+          </PrimitivesProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.getByTestId(`related-list-${historySection.title}`)).toBeTruthy();
+    expect(capturedChromeless).toBeUndefined();
+  });
+});
+
 describe("RelatedListSection — rowActions", () => {
   test("clicking a row action dispatches through the configured write-handler with the extracted payload, then refetches", async () => {
     const { dispatcher, writes, queryCount } = stubDispatcher();

package/src/components/__tests__/render-edit-screen-description.test.tsx

@@ -0,0 +1,132 @@
+// Regression coverage for kumiko-framework#2723: `EntityEditScreenDefinition.
+// description` / `ActionFormScreenDefinition.description` existed in the type
+// but was never rendered anywhere — used only as agent/API metadata
+// (packages/framework/src/api/server.ts). RenderEdit now renders it as the
+// form's subtitle, same visual slot section.description already fills for a
+// section (render-edit.tsx's `Section`), falling back to it only when no
+// `screen:<id>.subtitle` i18n override is set. `description` is run through
+// translate(): an i18n key (the established convention, e.g.
+// user-data-rights/feature.ts) resolves to its translation, plain prose
+// passes through unchanged (review finding on this PR).
+
+import { describe, expect, test } from "bun:test";
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { render } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { createStaticLocaleResolver, LocaleProvider, type TranslationsByLocale } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import { type CorePrimitives, type FormProps, PrimitivesProvider } from "../../primitives";
+import { RenderEdit } from "../render-edit";
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+function buildEntity(): EntityDefinition {
+  return {
+    fields: {
+      name: { type: "text", maxLength: 200, required: false, searchable: false, sortable: false },
+    },
+  };
+}
+
+function renderEditCapturingForm(
+  screen: EntityEditScreenDefinition,
+  extraTranslations?: TranslationsByLocale,
+): {
+  captured: FormProps | undefined;
+} {
+  let captured: FormProps | undefined;
+  const capturingForm = (props: FormProps): ReactNode => {
+    captured = props;
+    return props.children;
+  };
+  const primitives: CorePrimitives = {
+    Button: noop,
+    Banner: noop,
+    Field: passChildren,
+    Input: noop,
+    DataTable: noop,
+    Form: capturingForm,
+    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: "en-US" })}
+      fallbackBundles={
+        extraTranslations !== undefined
+          ? [extraTranslations, kumikoDefaultTranslations]
+          : [kumikoDefaultTranslations]
+      }
+    >
+      <PrimitivesProvider value={primitives}>
+        <RenderEdit
+          screen={screen}
+          entity={buildEntity()}
+          featureName="widgets"
+          initial={{ name: "" }}
+        />
+      </PrimitivesProvider>
+    </LocaleProvider>,
+  );
+  return { captured };
+}
+
+describe("RenderEdit — screen.description as form subtitle (fw#2723)", () => {
+  test("a screen with description renders it as the form's subtitle", () => {
+    const screen: EntityEditScreenDefinition = {
+      id: "widget-edit",
+      type: "entityEdit",
+      entity: "widget",
+      description: "Edit the widget's basic details.",
+      layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+    };
+
+    const { captured } = renderEditCapturingForm(screen);
+
+    expect(captured?.subtitle).toBe("Edit the widget's basic details.");
+  });
+
+  test("a description that is a known i18n key renders translated, not as the raw key", () => {
+    const screen: EntityEditScreenDefinition = {
+      id: "widget-edit",
+      type: "entityEdit",
+      entity: "widget",
+      description: "widgets:widget-edit.explainer",
+      layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+    };
+
+    const { captured } = renderEditCapturingForm(screen, {
+      "en-US": { "widgets:widget-edit.explainer": "Every field here is optional." },
+    });
+
+    expect(captured?.subtitle).toBe("Every field here is optional.");
+  });
+
+  test("a screen without description renders no subtitle prop at all (no empty placeholder)", () => {
+    const screen: EntityEditScreenDefinition = {
+      id: "widget-edit",
+      type: "entityEdit",
+      entity: "widget",
+      layout: { sections: [{ title: "Basics", fields: ["name"] }] },
+    };
+
+    const { captured } = renderEditCapturingForm(screen);
+
+    expect(captured).toBeDefined();
+    expect(captured && "subtitle" in captured).toBe(false);
+  });
+});

package/src/components/__tests__/render-field-select-display.test.tsx

@@ -0,0 +1,134 @@
+// SelectFieldDef.display travels the whole declarative chain (#2711):
+// EntityDefinition → computeEditViewModel → RenderField → InputProps. Without
+// it an app can only hope its labels fall under the renderer's heuristic.
+
+import { describe, expect, test } from "bun:test";
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { computeEditViewModel, type EditFieldViewModel } from "@cosmicdrift/kumiko-headless";
+import { render } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { type CorePrimitives, type InputProps, PrimitivesProvider } from "../../primitives";
+import { RenderField } from "../render-field";
+
+let captured: InputProps | undefined;
+const captureInput: ComponentType<InputProps> = (props) => {
+  captured = props;
+  return null;
+};
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: noop,
+  Field: passChildren,
+  Input: captureInput,
+  DataTable: noop,
+  Form: noop,
+  Section: noop,
+  Card: noop,
+  Grid: noop,
+  GridCell: noop,
+  Text: noop,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+const AREAS = ["jobs", "mail", "search", "events", "tenants"] as const;
+
+function buildEntity(display: "radio" | "dropdown" | undefined): EntityDefinition {
+  return {
+    fields: {
+      area: {
+        type: "select",
+        required: false,
+        options: AREAS,
+        ...(display !== undefined && { display }),
+      },
+      tags: {
+        type: "multiSelect",
+        required: false,
+        options: AREAS,
+        display: "checkboxes",
+      },
+    },
+  } as EntityDefinition;
+}
+
+const editScreen: EntityEditScreenDefinition = {
+  id: "ticket-edit",
+  type: "entityEdit",
+  entity: "ticket",
+  layout: { sections: [{ columns: 1, fields: ["area", "tags"] }] },
+} as EntityEditScreenDefinition;
+
+function viewModelField(entity: EntityDefinition, fieldName: string): EditFieldViewModel {
+  const vm = computeEditViewModel({
+    screen: editScreen,
+    entity,
+    values: { area: "jobs", tags: [] },
+    translate: (key) => key,
+    featureName: "helpdesk",
+  });
+  const section = vm.sections[0];
+  if (section === undefined || section.kind !== "fields") {
+    throw new Error("expected a fields section");
+  }
+  const field = section.fields.find((f) => f.field === fieldName);
+  if (field === undefined) throw new Error(`expected a ${fieldName} field`);
+  return field;
+}
+
+function renderField(field: EditFieldViewModel): InputProps {
+  captured = undefined;
+  render(
+    <LocaleProvider resolver={createStaticLocaleResolver({ locale: "en-US" })}>
+      <PrimitivesProvider value={testPrimitives}>
+        <RenderField field={field} onChange={() => {}} />
+      </PrimitivesProvider>
+    </LocaleProvider>,
+  );
+  if (captured === undefined) throw new Error("field did not render an Input");
+  return captured;
+}
+
+describe("RenderField — select display request", () => {
+  test('display: "radio" on the field definition reaches the Input', () => {
+    const field = viewModelField(buildEntity("radio"), "area");
+    expect(field.display).toBe("radio");
+    const input = renderField(field);
+    expect(input.kind).toBe("select");
+    if (input.kind !== "select") return;
+    expect(input.display).toBe("radio");
+  });
+
+  test('display: "dropdown" on the field definition reaches the Input', () => {
+    const input = renderField(viewModelField(buildEntity("dropdown"), "area"));
+    expect(input.kind).toBe("select");
+    if (input.kind !== "select") return;
+    expect(input.display).toBe("dropdown");
+  });
+
+  test("no display on the field definition leaves the Input to its own default", () => {
+    const field = viewModelField(buildEntity(undefined), "area");
+    expect(field.display).toBeUndefined();
+    const input = renderField(field);
+    expect(input.kind).toBe("select");
+    if (input.kind !== "select") return;
+    expect(input.display).toBeUndefined();
+  });
+
+  test('multiSelect keeps its own "checkboxes" display untouched', () => {
+    const field = viewModelField(buildEntity("radio"), "tags");
+    expect(field.display).toBe("checkboxes");
+  });
+});

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

@@ -155,14 +155,14 @@ export function RelatedListSection({
         {...(onRowClick !== undefined && { onRowClick })}
         {...(rowActions !== undefined && { rowActions })}
         {...(rowActionMode !== undefined && { rowActionMode })}
+        {...(hideTitle === true && { chromeless: true })}
       />
     );
 
-  // hideTitle (tabs mode) → this section carries no header content of its
-  // own, and RenderList's DataTable already draws its own card frame — a
-  // Section wrapper here would only add a second, nested card (fw record-
-  // screen-type polish). Stacked (non-tabs) sections keep their Section
-  // card since they render a visible title.
+  // 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;
 
   return (

package/src/components/render-edit.tsx

@@ -1036,7 +1036,13 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // Title + Subtitle, create/edit-bewusst. i18n-Keys (mode = "create"|"edit"):
   //   screen:<id>.<mode>.title / .<mode>.subtitle
   // Fallback-Kette: mode-spezifisch → generisch (screen:<id>.title/.subtitle).
-  // title falls back to screenId; subtitle to undefined (no subtitle).
+  // title falls back to screenId; subtitle falls back to screen.description,
+  // itself run through translate() so an i18n key (the established
+  // convention for description, e.g. bundled-features) resolves instead of
+  // showing the raw key — translate() returns the input unchanged for plain
+  // prose, same as it does for an unknown key (fw#2723 review). Same slot
+  // section.description already fills for a section. Falls back to
+  // undefined (no subtitle) when neither is set.
   const isCreate = (() => {
     const id = resolveExtensionEntityId(entityIdProp, vm.id);
     return id == null || id === "";
@@ -1053,7 +1059,9 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     return undefined;
   };
   const formTitle = resolveScreenText("title") ?? screen.id;
-  const formSubtitle = resolveScreenText("subtitle");
+  const formSubtitle =
+    resolveScreenText("subtitle") ??
+    (screen.description !== undefined ? translate(screen.description) : undefined);
 
   return (
     <ExtensionFormRegistryProvider value={extensionFormRegistry}>

package/src/components/render-field.tsx

@@ -689,6 +689,10 @@ function renderInput({
         labels !== undefined
           ? rawOptions.map((value: string) => ({ value, label: labels[value] ?? value }))
           : rawOptions;
+      // `display` is shared with multiSelect's "checkboxes", which is not a
+      // select presentation — narrow to the two a select field can request.
+      const display =
+        field.display === "radio" || field.display === "dropdown" ? field.display : undefined;
       return (
         <Input
           kind="select"
@@ -696,6 +700,7 @@ function renderInput({
           value={stringValue(field.value)}
           onChange={(v) => onChange(v)}
           options={selectOptions}
+          {...(display !== undefined && { display })}
         />
       );
     }

package/src/components/render-list.tsx

@@ -110,6 +110,10 @@ export type RenderListProps = {
   readonly onFilterChange?: (field: string, values: readonly string[]) => void;
   /** Reset aller aktiven Facets. */
   readonly onFilterReset?: () => void;
+  /** Forwarded to `DataTableProps.chromeless` — drops the table's own card
+   *  frame for a host that already provides one (relatedList in a tabs-mode
+   *  section, fw#2722). Default false. */
+  readonly chromeless?: boolean;
 };
 
 // Resolved-Form einer Toolbar-Action: KumikoScreen baut das aus dem
@@ -158,6 +162,7 @@ export function RenderList(props: RenderListProps): ReactNode {
     filterValues,
     onFilterChange,
     onFilterReset,
+    chromeless,
   } = props;
   // Wie RenderEdit: Translate-Fallback aus dem i18next-Context, sonst
   // wären Column-Header raw i18n-Keys.
@@ -372,6 +377,7 @@ export function RenderList(props: RenderListProps): ReactNode {
         {...(filterValues !== undefined && { filterValues })}
         {...(onFilterChange !== undefined && { onFilterChange })}
         {...(onFilterReset !== undefined && { onFilterReset })}
+        {...(chromeless !== undefined && { chromeless })}
         testId="render-list-table"
       />
     </>

package/src/primitives.tsx

@@ -322,6 +322,12 @@ export type InputProps =
       readonly disabled?: boolean;
       readonly required?: boolean;
       readonly hasError?: boolean;
+      /** Requested presentation. `"radio"` renders the options as a visible
+       *  radio group (WAI-ARIA radiogroup, one click per choice),
+       *  `"dropdown"` renders the combobox. Omitted = the implementation
+       *  decides; the web impl keeps its short-option-set heuristic. Custom
+       *  impls may ignore it — it is a request, not a contract. */
+      readonly display?: "radio" | "dropdown";
     }
   | ({
       // Tier 2.1c: Combobox / Searchable-Select. Single-Mode (multiple
@@ -612,6 +618,11 @@ export type DataTableProps = {
   readonly getRowTestId?: (row: ListRowViewModel) => string;
   /** Overrides the cell `data-testid` (default `cell-${row.id}-${field}`). */
   readonly getCellTestId?: (row: ListRowViewModel, field: string) => string;
+  /** Drops the table's own rounded/border/card background — for a host
+   *  that already provides the surrounding boundary (a tab panel, fw#2722)
+   *  and would otherwise show a card nested inside that boundary. Default
+   *  false: unchanged card-framed table. */
+  readonly chromeless?: boolean;
 };
 
 // ---- EmbeddedListInput (createEmbeddedListField widget) ----