@cosmicdrift/kumiko-renderer 0.208.2 → 0.209.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.208.2",
+  "version": "0.209.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.208.2",
-    "@cosmicdrift/kumiko-headless": "0.208.2",
+    "@cosmicdrift/kumiko-framework": "0.209.0",
+    "@cosmicdrift/kumiko-headless": "0.209.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -25,7 +25,7 @@
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "jsdom": "^29.1.1",
-    "@cosmicdrift/kumiko-locale-de": "0.208.2"
+    "@cosmicdrift/kumiko-locale-de": "0.209.0"
   },
   "repository": {
     "type": "git",

package/src/app/__tests__/list-filter-facets.test.tsx

@@ -0,0 +1,241 @@
+// fw#2224: ProjectionListBody had neither `filter` nor faceted filters —
+// only EntityListBody did (see kumiko-screen.tsx's buildFilterPayload/
+// buildFilterFacets doc). This proves both directions of the fix: entityList
+// keeps its exact pre-refactor payload/facet behavior after the shared
+// function extraction, and projectionList gains the same capability —
+// screen.filter and screen.facets reach payload.filter/payload.filters,
+// with boolean facets coerced from URL-state strings to real booleans.
+
+import { describe, expect, test } from "bun:test";
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+  ProjectionListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { act, render, waitFor } from "@testing-library/react";
+import { type ComponentType, type ReactNode, useState } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import { type CorePrimitives, type DataTableProps, PrimitivesProvider } from "../../primitives";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import type { NavApi } from "../nav";
+import { NavProvider } from "../nav";
+
+let capturedProps: DataTableProps | undefined;
+const captureDataTable: ComponentType<DataTableProps> = (props) => {
+  capturedProps = props;
+  return null;
+};
+// Indirection defeats TS narrowing `capturedProps` to `undefined` at read
+// sites — the compiler can't see that `captureDataTable` (a React render
+// callback) reassigns it between the reset and the read.
+const getCapturedProps = (): DataTableProps | undefined => capturedProps;
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: passChildren,
+  Field: passChildren,
+  Input: noop,
+  DataTable: captureDataTable,
+  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,
+};
+
+let queryCalls: Array<{ readonly type: string; readonly payload: unknown }> = [];
+
+function stubDispatcher(): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async (type: string, payload: unknown) => {
+      queryCalls.push({ type, payload });
+      return { isSuccess: true, data: { rows: [], nextCursor: null } };
+    }) 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: () => [],
+  };
+}
+
+// Stateful nav so setSearchParams (called by useListUrlState.setFilter)
+// actually re-renders the tree — a plain mock object wouldn't trigger React,
+// and toggling a facet would never reach a second query() call.
+function StatefulNav({ children }: { readonly children: ReactNode }): ReactNode {
+  const [params, setParams] = useState<Record<string, string>>({});
+  const value: NavApi = {
+    route: { screenId: "unused" },
+    navigate: () => {},
+    replace: () => {},
+    hrefFor: () => "",
+    searchParams: params,
+    setSearchParams: (updates) => {
+      setParams((prev) => {
+        const next = { ...prev };
+        for (const [k, v] of Object.entries(updates)) {
+          if (v === null) delete next[k];
+          else next[k] = v;
+        }
+        return next;
+      });
+    },
+  };
+  return <NavProvider value={value}>{children}</NavProvider>;
+}
+
+function renderScreen(schema: FeatureSchema, qn: string): void {
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "de-DE" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={stubDispatcher()}>
+        <StatefulNav>
+          <PrimitivesProvider value={testPrimitives}>
+            <KumikoScreen schema={schema} qn={qn} />
+          </PrimitivesProvider>
+        </StatefulNav>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("entityList facets — unchanged after the shared buildFilterFacets/buildFilterPayload extraction (fw#2224)", () => {
+  test("a filterable boolean field renders as a facet, and toggling it sends a coerced boolean in payload.filters", async () => {
+    queryCalls = [];
+    capturedProps = undefined;
+    const entity: EntityDefinition = {
+      fields: {
+        active: { type: "boolean", filterable: true, required: false },
+      },
+    };
+    const screen: EntityListScreenDefinition = {
+      id: "unit-list",
+      type: "entityList",
+      entity: "unit",
+      columns: ["active"],
+    };
+    const schema: FeatureSchema = {
+      featureName: "units",
+      entities: { unit: entity },
+      screens: [screen],
+    } as FeatureSchema;
+
+    renderScreen(schema, "units:screen:unit-list");
+
+    await waitFor(() => expect(capturedProps).toBeDefined());
+    const props = getCapturedProps();
+    if (props === undefined) throw new Error("DataTable was not rendered");
+    expect(props.filterFacets).toHaveLength(1);
+    expect(props.filterFacets?.[0]?.field).toBe("active");
+    expect(props.filterFacets?.[0]?.options).toEqual([
+      { value: "true", label: expect.any(String) },
+      { value: "false", label: expect.any(String) },
+    ]);
+
+    const countBeforeToggle = queryCalls.length;
+    await act(async () => {
+      props.onFilterChange?.("active", ["true"]);
+    });
+    await waitFor(() => expect(queryCalls.length).toBeGreaterThan(countBeforeToggle));
+    const lastPayload = queryCalls[queryCalls.length - 1]?.payload;
+    expect(lastPayload).toMatchObject({
+      filters: [{ field: "active", op: "in", value: [true] }],
+    });
+  });
+});
+
+describe("projectionList filter + facets (fw#2224)", () => {
+  test("screen.filter is sent verbatim in the query payload", async () => {
+    queryCalls = [];
+    const screen: ProjectionListScreenDefinition = {
+      id: "member-list",
+      type: "projectionList",
+      query: "ledger:query:member:list",
+      columns: ["status"],
+      filter: { field: "tier", op: "eq", value: "gold" },
+    };
+    const schema: FeatureSchema = {
+      featureName: "ledger",
+      entities: {},
+      screens: [screen],
+    } as FeatureSchema;
+
+    renderScreen(schema, "ledger:screen:member-list");
+
+    await waitFor(() => expect(queryCalls.length).toBeGreaterThan(0));
+    expect(queryCalls[0]?.payload).toMatchObject({
+      filter: { field: "tier", op: "eq", value: "gold" },
+    });
+  });
+
+  test("a boolean facet renders with the screen's explicit labels, and toggling it sends a coerced boolean in payload.filters", async () => {
+    queryCalls = [];
+    capturedProps = undefined;
+    const screen: ProjectionListScreenDefinition = {
+      id: "member-list",
+      type: "projectionList",
+      query: "ledger:query:member:list",
+      columns: ["active"],
+      facets: [
+        {
+          field: "active",
+          type: "boolean",
+          label: "Active",
+          trueLabel: "Active",
+          falseLabel: "Inactive",
+        },
+      ],
+    };
+    const schema: FeatureSchema = {
+      featureName: "ledger",
+      entities: {},
+      screens: [screen],
+    } as FeatureSchema;
+
+    renderScreen(schema, "ledger:screen:member-list");
+
+    await waitFor(() => expect(capturedProps).toBeDefined());
+    const props = getCapturedProps();
+    if (props === undefined) throw new Error("DataTable was not rendered");
+    expect(props.filterFacets).toEqual([
+      {
+        field: "active",
+        label: "Active",
+        options: [
+          { value: "true", label: "Active" },
+          { value: "false", label: "Inactive" },
+        ],
+      },
+    ]);
+
+    const countBeforeToggle = queryCalls.length;
+    await act(async () => {
+      props.onFilterChange?.("active", ["true"]);
+    });
+    await waitFor(() => expect(queryCalls.length).toBeGreaterThan(countBeforeToggle));
+    const lastPayload = queryCalls[queryCalls.length - 1]?.payload;
+    expect(lastPayload).toMatchObject({
+      filters: [{ field: "active", op: "in", value: [true] }],
+    });
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -6,6 +6,7 @@ import type {
   EntityDefinition,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
+  ListFacetSpec,
   ProjectionDetailScreenDefinition,
   ProjectionListScreenDefinition,
   RowAction,
@@ -24,7 +25,7 @@ import type {
   SubmitResult,
   Translate,
 } from "@cosmicdrift/kumiko-headless";
-import { fieldLabelKey } from "@cosmicdrift/kumiko-headless";
+import { fieldLabelKey, fieldOptionLabelKey } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { extractCreatedId } from "../components/reference-create-dialog";
 import { RenderEdit, type RenderEditAction } from "../components/render-edit";
@@ -858,6 +859,226 @@ 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 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(
+  fields: Readonly<Record<string, unknown>>,
+  featureName: string,
+  entityName: string,
+  translate: Translate,
+): ResolvedFacetSpec[] {
+  const out: ResolvedFacetSpec[] = [];
+  for (const [field, rawDef] of Object.entries(fields)) {
+    // entity.fields ist am Renderer-Layer schwach getypt (Record<string,
+    // unknown>, vom Schema deserialisiert) — Boundary-Cast wie buildInitialValues.
+    const def = rawDef as { type?: string; filterable?: boolean; options?: readonly string[] };
+    if (def.filterable !== true) continue;
+    const label = translate(fieldLabelKey(featureName, entityName, field));
+    if (def.type === "select" && Array.isArray(def.options)) {
+      out.push({
+        field,
+        type: "select",
+        label,
+        options: def.options.map((value) => ({
+          value,
+          label: translate(fieldOptionLabelKey(featureName, entityName, field, value)),
+        })),
+      });
+    } else if (def.type === "boolean") {
+      out.push({
+        field,
+        type: "boolean",
+        label,
+        options: [
+          {
+            value: "true",
+            label: translate(fieldOptionLabelKey(featureName, entityName, field, "true")),
+          },
+          {
+            value: "false",
+            label: translate(fieldOptionLabelKey(featureName, entityName, field, "false")),
+          },
+        ],
+      });
+    }
+  }
+  return out;
+}
+
+// projectionList adapter — a projectionList has no entity/i18n convention to
+// derive labels from, so ListFacetSpec carries every label explicitly
+// (fw#2224); this just reshapes it into the same ResolvedFacetSpec the
+// entityList adapter produces.
+function resolveProjectionFacetSpecs(
+  facets: readonly ListFacetSpec[] | undefined,
+): ResolvedFacetSpec[] {
+  if (facets === undefined) return [];
+  return facets.map((facet) =>
+    facet.type === "select"
+      ? { field: facet.field, type: "select", label: facet.label, options: facet.options }
+      : {
+          field: facet.field,
+          type: "boolean",
+          label: facet.label,
+          options: [
+            { value: "true", label: facet.trueLabel },
+            { value: "false", label: facet.falseLabel },
+          ],
+        },
+  );
+}
+
+// ---- toolbarAction kind:"drawer" (fw#2225) ----
+//
+// Shared between EntityListBody and ProjectionListBody: state for "which
+// drawer-kind toolbar action is currently open" plus a host component that
+// mounts the referenced actionForm inside the Drawer primitive. Reuses
+// ActionFormBody (no second, parallel form renderer) with onSuccess/
+// onCancelOverride so submit-success closes the drawer + refetches the
+// list instead of navigating, mirroring what a full-page actionForm would
+// do via `redirect`.
+type ToolbarDrawerAction = Extract<ToolbarAction, { kind: "drawer" }>;
+
+function useToolbarDrawerAction(schema: FeatureSchema): {
+  readonly drawerAction: ToolbarDrawerAction | null;
+  readonly drawerScreen: ActionFormScreenDefinition | undefined;
+  readonly openDrawer: (action: ToolbarDrawerAction) => void;
+  readonly closeDrawer: () => void;
+} {
+  const [drawerAction, setDrawerAction] = useState<ToolbarDrawerAction | null>(null);
+  const drawerScreen = useMemo(() => {
+    if (drawerAction === null) return undefined;
+    // Same same-feature, short-id resolution as runNavigate — the drawer's
+    // `screen` reference is scoped to schema.screens, not cross-feature.
+    return schema.screens.find(
+      (s): s is ActionFormScreenDefinition =>
+        s.type === "actionForm" && lastSegment(s.id) === drawerAction.screen,
+    );
+  }, [drawerAction, schema.screens]);
+  const openDrawer = useCallback((action: ToolbarDrawerAction) => setDrawerAction(action), []);
+  const closeDrawer = useCallback(() => setDrawerAction(null), []);
+  return { drawerAction, drawerScreen, openDrawer, closeDrawer };
+}
+
+function ToolbarDrawerHost({
+  schema,
+  drawerAction,
+  drawerScreen,
+  userRoles,
+  translate,
+  onClose,
+  onSuccess,
+}: {
+  readonly schema: FeatureSchema;
+  readonly drawerAction: ToolbarDrawerAction | null;
+  readonly drawerScreen: ActionFormScreenDefinition | undefined;
+  readonly userRoles: readonly string[] | undefined;
+  readonly translate?: Translate;
+  readonly onClose: () => void;
+  readonly onSuccess: () => void;
+}): ReactNode {
+  const { Drawer, Banner, Text } = usePrimitives();
+  const t = useTranslation();
+  const effectiveTranslate = translate ?? t;
+  // Drawer is an optional Core-Primitive (additive rollout) — same "skip +
+  // warn once" precedent as rowActions without a mounted DispatcherProvider
+  // above, instead of crashing when a web app hasn't upgraded its
+  // createKumikoApp wiring yet.
+  useEffect(() => {
+    if (drawerAction !== null && Drawer === undefined) {
+      // biome-ignore lint/suspicious/noConsole: dev-warning for a setup error
+      console.warn(
+        `[kumiko] toolbarAction "${drawerAction.id}" is kind:"drawer", but no <Drawer> primitive is registered — it will not open. createKumikoApp() from kumiko-renderer-web wires it automatically.`,
+      );
+    }
+  }, [drawerAction, Drawer]);
+
+  if (drawerAction === null || Drawer === undefined) return null;
+
+  // Access mirrors kind:"navigate" exactly: the toolbar button itself stays
+  // visible either way (same as navigate — access is enforced at the
+  // target, not by hiding the trigger), but the drawer shows the same
+  // "Access denied" state KumikoScreen's top-level gate would show for a
+  // direct hit on that screen, never the form.
+  const allowed = screenAccessAllows(drawerScreen?.access, userRoles);
+
+  return (
+    <Drawer
+      open={true}
+      onOpenChange={(open) => {
+        if (!open) onClose();
+      }}
+      title={effectiveTranslate(drawerAction.label)}
+      testId={`toolbar-drawer-${drawerAction.id}`}
+    >
+      {drawerScreen === undefined ? (
+        <Banner padded variant="error" testId="kumiko-toolbar-drawer-not-found">
+          Screen not found: <Text variant="code">{drawerAction.screen}</Text>
+        </Banner>
+      ) : !allowed ? (
+        <Banner padded variant="error" testId="kumiko-toolbar-drawer-access-denied">
+          Access denied: <Text variant="code">{drawerAction.screen}</Text>
+        </Banner>
+      ) : (
+        <ActionFormBody
+          schema={schema}
+          screen={drawerScreen}
+          {...(translate !== undefined && { translate })}
+          onSuccess={onSuccess}
+          onCancelOverride={onClose}
+        />
+      )}
+    </Drawer>
+  );
+}
+
 function EntityListScreen({
   schema,
   screen,
@@ -911,6 +1132,8 @@ function EntityListBody({
   const { Banner } = usePrimitives();
   const queryType = entityQueryCommand(featureName, screen.entity, "list");
   const nav = useNav();
+  const userRoles = useUserRoles();
+  const { drawerAction, drawerScreen, openDrawer, closeDrawer } = useToolbarDrawerAction(schema);
 
   // URL-State: sort/dir/q/page leben unter dem screen.id-Namespace
   // (`/orders?orders.sort=createdAt&orders.dir=desc&orders.q=acme`),
@@ -947,28 +1170,18 @@ function EntityListBody({
   }, [useInfinite, sortQKey]);
 
   // User-gewählte Faceted-Filter aus dem URL-State → payload.filters.
-  // Boolean-Felder: "true"/"false"-Strings zu echten Booleans coercen
-  // (DB-Spalte ist boolean). Alles als op:"in" (Multi-Select-Semantik).
-  const filterPayload = useMemo(() => {
-    const out: { field: string; op: "in"; value: unknown }[] = [];
-    for (const [field, values] of Object.entries(urlState.filters)) {
-      if (values.length === 0) continue;
-      // `id` is a base column (not in entity.fields), 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;
-      }
-      // entity.fields ist am Renderer-Layer schwach getypt (vom Schema
-      // deserialisiert) — Boundary-Cast wie buildInitialValues.
-      const def = entity.fields[field] as { type?: string } | undefined;
-      if (def === undefined) continue;
-      const value = def.type === "boolean" ? values.map((v) => v === "true") : values;
-      out.push({ field, op: "in", value });
-    }
-    return out;
-  }, [urlState.filters, entity.fields]);
+  // typeOf liest den Field-Type direkt aus entity.fields (nicht gated auf
+  // filterable — bewusst permissiv, siehe buildFilterPayload-Doc).
+  const filterPayload = useMemo(
+    () =>
+      buildFilterPayload(urlState.filters, (field) => {
+        // entity.fields ist am Renderer-Layer schwach getypt (vom Schema
+        // deserialisiert) — Boundary-Cast wie buildInitialValues.
+        const def = entity.fields[field] as { type?: string } | undefined;
+        return def?.type;
+      }),
+    [urlState.filters, entity.fields],
+  );
 
   // Entity-only additions (screen.filter, faceted filters) layer on top of
   // the shared buildListQueryPayload — projectionList has neither.
@@ -1052,52 +1265,13 @@ function EntityListBody({
   // Faceted-Filter: ein Dropdown pro filterable select/boolean-Feld.
   // Labels + select-Option-Labels über dieselbe i18n-Konvention wie die
   // Spalten-Header (fieldLabelKey / :option:<value>).
-  const filterFacets = useMemo<DataTableFacet[]>(() => {
-    const out: DataTableFacet[] = [];
-    for (const [field, rawDef] of Object.entries(entity.fields)) {
-      // entity.fields ist am Renderer-Layer schwach getypt (Record<string,
-      // unknown>, vom Schema deserialisiert) — Boundary-Cast wie buildInitialValues.
-      const def = rawDef as {
-        type?: string;
-        filterable?: boolean;
-        options?: readonly string[];
-      };
-      if (def.filterable !== true) continue;
-      const label = effectiveTranslate(fieldLabelKey(featureName, screen.entity, field));
-      if (def.type === "select" && Array.isArray(def.options)) {
-        out.push({
-          field,
-          label,
-          options: def.options.map((value) => ({
-            value,
-            label: effectiveTranslate(
-              `${featureName}:entity:${screen.entity}:field:${field}:option:${value}`,
-            ),
-          })),
-        });
-      } else if (def.type === "boolean") {
-        out.push({
-          field,
-          label,
-          options: [
-            {
-              value: "true",
-              label: effectiveTranslate(
-                `${featureName}:entity:${screen.entity}:field:${field}:option:true`,
-              ),
-            },
-            {
-              value: "false",
-              label: effectiveTranslate(
-                `${featureName}:entity:${screen.entity}:field:${field}:option:false`,
-              ),
-            },
-          ],
-        });
-      }
-    }
-    return out;
-  }, [entity.fields, featureName, screen.entity, effectiveTranslate]);
+  const filterFacets = useMemo<DataTableFacet[]>(
+    () =>
+      buildFilterFacets(
+        resolveEntityFacetSpecs(entity.fields, featureName, screen.entity, effectiveTranslate),
+      ),
+    [entity.fields, featureName, screen.entity, effectiveTranslate],
+  );
 
   // Soft-Dispatcher: in Tests die ohne DispatcherProvider mounten,
   // bleibt rowActions undefined statt zu crashen. Echte Apps haben
@@ -1235,6 +1409,14 @@ function EntityListBody({
             onTrigger: () => nav.navigate({ screenId: action.screen }),
           };
         }
+        if (action.kind === "drawer") {
+          return {
+            id: action.id,
+            label: effectiveTranslate(action.label),
+            ...(action.style !== undefined && { style: action.style }),
+            onTrigger: () => openDrawer(action),
+          };
+        }
         // writeHandler — braucht Dispatcher. Wenn keiner mounted ist,
         // skippen wir die Action statt zu crashen (gleiche Logik wie
         // bei rowActions; einmaliger Warn-Log dort reicht).
@@ -1265,7 +1447,7 @@ function EntityListBody({
         };
       })
       .filter((a: ToolbarActionButton | null): a is ToolbarActionButton => a !== null);
-  }, [screen.toolbarActions, effectiveTranslate, nav, dispatcher, rowsQuery.refetch]);
+  }, [screen.toolbarActions, effectiveTranslate, nav, dispatcher, rowsQuery.refetch, openDrawer]);
 
   if (rowsQuery.loading && rowsQuery.data === null) {
     return (
@@ -1329,34 +1511,48 @@ function EntityListBody({
   const renderRows = useInfinite ? accumulated : (rowsQuery.data?.rows ?? []);
 
   return (
-    <RenderList
-      screen={screen}
-      entity={entity}
-      rows={renderRows}
-      featureName={featureName}
-      searchable={searchable}
-      searchValue={urlState.q}
-      onSearchChange={urlState.setQ}
-      sort={effectiveSort}
-      onSortChange={urlState.setSort}
-      {...(pager !== undefined && { pager })}
-      {...(rowActions !== undefined && { rowActions })}
-      {...(toolbarActions !== undefined && toolbarActions.length > 0 && { toolbarActions })}
-      {...(useInfinite && {
-        onReachEnd: loadMore,
-        loadingMore: rowsQuery.loading,
-        hasMore,
-      })}
-      {...(onCreate !== undefined && { onCreate })}
-      {...(translate !== undefined && { translate })}
-      {...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick })}
-      {...(filterFacets.length > 0 && {
-        filterFacets,
-        filterValues: urlState.filters,
-        onFilterChange: urlState.setFilter,
-        onFilterReset: urlState.clearFilters,
-      })}
-    />
+    <>
+      <RenderList
+        screen={screen}
+        entity={entity}
+        rows={renderRows}
+        featureName={featureName}
+        searchable={searchable}
+        searchValue={urlState.q}
+        onSearchChange={urlState.setQ}
+        sort={effectiveSort}
+        onSortChange={urlState.setSort}
+        {...(pager !== undefined && { pager })}
+        {...(rowActions !== undefined && { rowActions })}
+        {...(toolbarActions !== undefined && toolbarActions.length > 0 && { toolbarActions })}
+        {...(useInfinite && {
+          onReachEnd: loadMore,
+          loadingMore: rowsQuery.loading,
+          hasMore,
+        })}
+        {...(onCreate !== undefined && { onCreate })}
+        {...(translate !== undefined && { translate })}
+        {...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick })}
+        {...(filterFacets.length > 0 && {
+          filterFacets,
+          filterValues: urlState.filters,
+          onFilterChange: urlState.setFilter,
+          onFilterReset: urlState.clearFilters,
+        })}
+      />
+      <ToolbarDrawerHost
+        schema={schema}
+        drawerAction={drawerAction}
+        drawerScreen={drawerScreen}
+        userRoles={userRoles}
+        {...(translate !== undefined && { translate })}
+        onClose={closeDrawer}
+        onSuccess={() => {
+          closeDrawer();
+          void rowsQuery.refetch();
+        }}
+      />
+    </>
   );
 }
 
@@ -1385,6 +1581,8 @@ function ProjectionListBody({
   const nav = useNav();
   const dispatcher = useOptionalDispatcher();
   const effectiveTranslate = translate ?? t;
+  const userRoles = useUserRoles();
+  const { drawerAction, drawerScreen, openDrawer, closeDrawer } = useToolbarDrawerAction(schema);
 
   // searchable/sortable/paginated are derived at buildAppSchema time from the
   // query handler's Zod schema (fw#2165) — not authored on the screen.
@@ -1408,22 +1606,56 @@ function ProjectionListBody({
   // "infinite" on a paginated projectionList is silently a no-op today.
   const usePager = paginated && (screen.pagination ?? "pages") === "pages";
 
-  const queryPayload = useMemo(
+  // Facets (fw#2224) — a projectionList has no entity, so screen.facets is
+  // the only field inventory; resolveProjectionFacetSpecs reshapes its
+  // explicit labels into the same ResolvedFacetSpec the entityList adapter
+  // produces, so both feed the same buildFilterFacets/buildFilterPayload.
+  const facetSpecs = useMemo(() => resolveProjectionFacetSpecs(screen.facets), [screen.facets]);
+  const filterPayload = useMemo(
     () =>
-      buildListQueryPayload({
-        limit,
-        search: activeSearch,
-        sort: activeSort,
-        usePager,
-        page: urlState.page,
-        useInfinite: false,
-        cursor: undefined,
-      }),
-    [limit, activeSearch, activeSort, usePager, urlState.page],
+      buildFilterPayload(
+        urlState.filters,
+        (field) => facetSpecs.find((spec) => spec.field === field)?.type,
+      ),
+    [urlState.filters, facetSpecs],
   );
 
+  const queryPayload = useMemo(() => {
+    const payload = buildListQueryPayload({
+      limit,
+      search: activeSearch,
+      sort: activeSort,
+      usePager,
+      page: urlState.page,
+      useInfinite: false,
+      cursor: undefined,
+    });
+    // Gated on screen.filter/screen.facets being declared (not just on
+    // urlState/filterPayload happening to carry a value) — same rule as
+    // activeSearch/activeSort above: a stale URL must not smuggle a param
+    // the bound query's Zod schema doesn't accept (fw#2165 pattern).
+    if (screen.filter !== undefined) {
+      payload["filter"] = screen.filter;
+    }
+    if (screen.facets !== undefined && filterPayload.length > 0) {
+      payload["filters"] = filterPayload;
+    }
+    return payload;
+  }, [
+    limit,
+    activeSearch,
+    activeSort,
+    usePager,
+    urlState.page,
+    screen.filter,
+    screen.facets,
+    filterPayload,
+  ]);
+
   const rowsQuery = useQuery<PagedRows>(screen.query, queryPayload, { live: true });
 
+  const filterFacets = useMemo<DataTableFacet[]>(() => buildFilterFacets(facetSpecs), [facetSpecs]);
+
   const runNavigate = useCallback(
     (action: RowActionNavigate, row: ListRowViewModel) => {
       const entityId =
@@ -1516,6 +1748,15 @@ function ProjectionListBody({
         });
         continue;
       }
+      if (action.kind === "drawer") {
+        out.push({
+          id: action.id,
+          label: effectiveTranslate(action.label),
+          ...(action.style !== undefined && { style: action.style }),
+          onTrigger: () => openDrawer(action),
+        });
+        continue;
+      }
       // writeHandler — analog entityList; ohne Dispatcher skippen statt crashen.
       if (dispatcher === undefined) continue;
       out.push({
@@ -1543,7 +1784,7 @@ function ProjectionListBody({
       });
     }
     return out.length > 0 ? out : undefined;
-  }, [screen.toolbarActions, effectiveTranslate, nav, dispatcher, rowsQuery.refetch]);
+  }, [screen.toolbarActions, effectiveTranslate, nav, dispatcher, rowsQuery.refetch, openDrawer]);
 
   if (rowsQuery.loading && rowsQuery.data === null) {
     return (
@@ -1594,22 +1835,42 @@ function ProjectionListBody({
       : undefined;
 
   return (
-    <RenderList
-      screen={listScreen}
-      entity={entity}
-      rows={rowsQuery.data?.rows ?? []}
-      featureName={schema.featureName}
-      searchable={searchable}
-      searchValue={urlState.q}
-      onSearchChange={urlState.setQ}
-      sort={activeSort}
-      onSortChange={urlState.setSort}
-      {...(pager !== undefined && { pager })}
-      {...(rowActions !== undefined && { rowActions })}
-      {...(toolbarActions !== undefined && { toolbarActions })}
-      {...(translate !== undefined && { translate })}
-      {...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick })}
-    />
+    <>
+      <RenderList
+        screen={listScreen}
+        entity={entity}
+        rows={rowsQuery.data?.rows ?? []}
+        featureName={schema.featureName}
+        searchable={searchable}
+        searchValue={urlState.q}
+        onSearchChange={urlState.setQ}
+        sort={activeSort}
+        onSortChange={urlState.setSort}
+        {...(pager !== undefined && { pager })}
+        {...(rowActions !== undefined && { rowActions })}
+        {...(toolbarActions !== undefined && { toolbarActions })}
+        {...(translate !== undefined && { translate })}
+        {...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick })}
+        {...(filterFacets.length > 0 && {
+          filterFacets,
+          filterValues: urlState.filters,
+          onFilterChange: urlState.setFilter,
+          onFilterReset: urlState.clearFilters,
+        })}
+      />
+      <ToolbarDrawerHost
+        schema={schema}
+        drawerAction={drawerAction}
+        drawerScreen={drawerScreen}
+        userRoles={userRoles}
+        {...(translate !== undefined && { translate })}
+        onClose={closeDrawer}
+        onSuccess={() => {
+          closeDrawer();
+          void rowsQuery.refetch();
+        }}
+      />
+    </>
   );
 }
 
@@ -1833,6 +2094,8 @@ function ProjectionDetailBody({
       onCancel={screen.listScreenId !== undefined ? navigateToList : undefined}
       {...(headerActions !== undefined && { actions: headerActions })}
       {...(translate !== undefined && { translate })}
+      valueDisplay={screen.valueDisplay ?? "text"}
+      hideActions={screen.hideActions === true}
     />
   );
 }
@@ -1849,10 +2112,21 @@ function ActionFormBody({
   schema,
   screen,
   translate,
+  onSuccess,
+  onCancelOverride,
 }: {
   readonly schema: FeatureSchema;
   readonly screen: ActionFormScreenDefinition;
   readonly translate?: Translate;
+  /** Drawer-hosted usage (toolbarAction kind:"drawer", fw#2225): called
+   *  instead of the redirect-based navigation on successful submit, so the
+   *  host closes the drawer + refetches its list regardless of whether
+   *  `screen.redirect` is set — a full-page redirect would navigate away
+   *  from the list the drawer sits on top of. */
+  readonly onSuccess?: () => void;
+  /** Drawer-hosted usage: replaces the cancelTarget/redirect-based Cancel
+   *  handler so Cancel closes the drawer instead of navigating. */
+  readonly onCancelOverride?: () => void;
 }): ReactNode {
   const nav = useNav();
   const synthEntity = useMemo(() => synthesizeActionFormEntity(screen.fields), [screen.fields]);
@@ -1868,24 +2142,30 @@ function ActionFormBody({
   );
   const handleSubmitted = useCallback(
     (result: SubmitResult<unknown>) => {
+      if (!result.isSuccess) return;
+      if (onSuccess !== undefined) {
+        onSuccess();
+        return;
+      }
       // Redirect ist optional. Bei isSuccess + redirect → nav.navigate.
       // Author entscheidet bewusst ob "stay on form" (default) oder
       // "back to list" (typisch bei Create-style Aktionen).
-      if (result.isSuccess && screen.redirect !== undefined) {
+      if (screen.redirect !== undefined) {
         nav.navigate({ screenId: lastSegment(screen.redirect) });
       }
     },
-    [nav, screen.redirect],
+    [nav, screen.redirect, onSuccess],
   );
   // Cancel ist nur sinnvoll wenn ein Navigations-Ziel existiert —
   // sonst hätte der Button nirgendwo hin zu navigieren. cancelTarget
   // gewinnt über redirect; `false` schaltet den Button explizit ab
   // (Single-Action-Screens, wo Cancel nur Submit-ohne-Senden wäre).
   const handleCancel = useMemo<(() => void) | undefined>(() => {
+    if (onCancelOverride !== undefined) return onCancelOverride;
     const target = screen.cancelTarget ?? screen.redirect;
     if (target === undefined || target === false) return undefined;
     return () => nav.navigate({ screenId: lastSegment(target) });
-  }, [nav, screen.redirect, screen.cancelTarget]);
+  }, [nav, screen.redirect, screen.cancelTarget, onCancelOverride]);
   return (
     <RenderEdit
       screen={synthScreen}

package/src/components/render-edit.tsx

@@ -210,6 +210,13 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
    *  `onControlsReady`'s `submit`. Omitting this prop keeps unchanged
    *  behavior. */
   readonly hideActions?: boolean;
+  /** "form" (default) — every field renders as its Input widget, disabled
+   *  when `field.readOnly`, unchanged behavior. "text" renders a
+   *  `field.readOnly` field as plain text instead of a disabled Input
+   *  (ProjectionDetailBody's read view, fw#2245) — editable fields are
+   *  unaffected either way, so this only changes forms that already have
+   *  readOnly fields. */
+  readonly valueDisplay?: "form" | "text";
 };
 
 export type RenderEditAction = {
@@ -427,6 +434,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     fields: fieldsFilter,
     disabled = false,
     hideActions,
+    valueDisplay = "form",
   } = props;
   const { customSubmit } = props;
   // Translate-Fallback: wenn der Caller keine Translate-Fn übergibt,
@@ -1358,6 +1366,8 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
                       fieldAppendix: fieldAppendix(field.field),
                     })}
                     allIssues={snapshot.errors}
+                    valueDisplay={valueDisplay}
+                    row={snapshot.values}
                   />
                 ))}
               </Grid>
@@ -1442,6 +1452,10 @@ type GridCellForFieldProps = {
   /** Full issues-by-path map (FormSnapshot.errors) — passed through for
    *  embedded-list fields, which bucket row-/cell-level issues themselves. */
   readonly allIssues: Readonly<Record<string, readonly FieldIssue[]>>;
+  /** Passed through to RenderField unchanged — see RenderEditProps.valueDisplay. */
+  readonly valueDisplay: "form" | "text";
+  /** Passed through to RenderField as `row` — see RenderFieldProps.row. */
+  readonly row: Readonly<Record<string, unknown>>;
 };
 
 function GridCellForField({
@@ -1454,6 +1468,8 @@ function GridCellForField({
   labelAppendix,
   fieldAppendix,
   allIssues,
+  valueDisplay,
+  row,
 }: GridCellForFieldProps): ReactNode {
   // RenderField renders nothing for a hidden field, but the GridCell around it still claims the row.
   if (!field.visible) return null;
@@ -1469,6 +1485,8 @@ function GridCellForField({
         {...(labelAppendix !== undefined && { labelAppendix })}
         {...(fieldAppendix !== undefined && { fieldAppendix })}
         allIssues={allIssues}
+        valueDisplay={valueDisplay}
+        row={row}
       />
     </GridCell>
   );

package/src/components/render-field.tsx

@@ -1,11 +1,18 @@
-import type { EntityEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
 import {
+  type EntityEditScreenDefinition,
+  type FieldRenderer,
+  isFormatSpec,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import {
+  applyFormatSpec,
   currencyDecimals,
   type EditFieldViewModel,
   type FieldIssue,
 } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode, useCallback, useMemo, useState } from "react";
 import { useAppFeatures } from "../app/app-features-context";
+import { useColumnRenderer } from "../app/column-renderers";
+import { extensionSectionName } from "../app/extension-sections";
 import { toKebab } from "../app/qn";
 import { screenAccessAllows } from "../app/screen-access";
 import { useUserRoles } from "../context/user-roles-context";
@@ -48,6 +55,17 @@ export type RenderFieldProps = {
    *  (`${field}.${rowIndex}` / `${field}.${rowIndex}.${cellField}`).
    *  Other field types ignore this prop. */
   readonly allIssues?: Readonly<Record<string, readonly FieldIssue[]>>;
+  /** "form" (default) renders every field as its editable Input, disabled
+   *  when `field.readOnly` — unchanged behavior. "text" renders a
+   *  `field.readOnly` field as plain text instead (projectionDetail's read
+   *  view, fw#2245); editable fields are untouched by this prop either way. */
+  readonly valueDisplay?: "form" | "text";
+  /** Current form values, keyed by field name — only consulted when
+   *  `field.renderer` resolves to a `{ react: { __component } }` registry
+   *  component, passed through as `ColumnRendererProps.row` (same contract
+   *  as list-column renderers, fw#2245). Omitted → falls back to a
+   *  single-key `{ [field.field]: field.value }` row. */
+  readonly row?: Readonly<Record<string, unknown>>;
 };
 
 export function RenderField({
@@ -58,6 +76,8 @@ export function RenderField({
   labelAppendix,
   fieldAppendix,
   allIssues,
+  valueDisplay = "form",
+  row,
 }: RenderFieldProps): ReactNode {
   const { Field, Input, Banner, Text } = usePrimitives();
   // App-Locale (i18n) für money/date-Inputs — sonst fielen sie auf
@@ -71,12 +91,24 @@ export function RenderField({
 
   const id = inputId(field);
   const hasError = issues !== undefined && issues.length > 0;
+  // An author-declared renderer always wins over the input widget, same as
+  // the list-column path (render-list.tsx). Only takes effect once the field
+  // is actually readOnly — a FormatSpec/PlatformComponent renderer has no
+  // editable widget of its own, so applying it to an editable field would
+  // silently make that field un-editable (fw#2245).
+  const readOnlyText = valueDisplay === "text" && field.readOnly && field.renderer === undefined;
 
   // Reference-Field rendert eine eigene Component — sie nutzt
   // useQuery() für den Live-Lookup, also muss sie als React-
   // Komponente gemountet werden (nicht als pure render-Call).
   const control =
-    field.type === "embedded" && field.embeddedListCells !== undefined ? (
+    field.readOnly && field.renderer !== undefined ? (
+      <FieldRendererOutput
+        field={field}
+        renderer={field.renderer}
+        {...(row !== undefined && { row })}
+      />
+    ) : field.type === "embedded" && field.embeddedListCells !== undefined ? (
       <EmbeddedListField
         field={field}
         id={id}
@@ -85,14 +117,20 @@ export function RenderField({
         featureName={featureName ?? ""}
       />
     ) : field.type === "reference" ? (
-      <ReferenceInput
-        field={field}
-        id={id}
-        hasError={hasError}
-        onChange={onChange}
-        Input={Input}
-        featureName={featureName ?? ""}
-      />
+      readOnlyText ? (
+        <ReadOnlyReferenceValue field={field} featureName={featureName ?? ""} />
+      ) : (
+        <ReferenceInput
+          field={field}
+          id={id}
+          hasError={hasError}
+          onChange={onChange}
+          Input={Input}
+          featureName={featureName ?? ""}
+        />
+      )
+    ) : readOnlyText && !isComplexFieldType(field.type) ? (
+      <Text testId={`field-value-${field.field}`}>{readOnlyDisplayText(field, appLocale)}</Text>
     ) : (
       renderInput({ field, id, hasError, onChange, Input, appLocale, Banner, Text, t })
     );
@@ -296,6 +334,87 @@ function inputId(field: EditFieldViewModel): string {
   return `kumiko-edit-${field.field}`;
 }
 
+// Doesn't resolve the `string` (cross-feature QN) FieldRenderer variant — the
+// list-column path (DataTableCell) doesn't either, so this stays in parity.
+function FieldRendererOutput({
+  field,
+  renderer,
+  row,
+}: {
+  readonly field: EditFieldViewModel;
+  readonly renderer: FieldRenderer;
+  readonly row?: Readonly<Record<string, unknown>>;
+}): ReactNode {
+  const { Text } = usePrimitives();
+  const componentName =
+    !isFormatSpec(renderer) && typeof renderer === "object" && renderer !== null
+      ? extensionSectionName(renderer)
+      : undefined;
+  const Component = useColumnRenderer(componentName);
+  if (isFormatSpec(renderer)) {
+    return (
+      <Text testId={`field-value-${field.field}`}>{applyFormatSpec(renderer, field.value)}</Text>
+    );
+  }
+  if (componentName !== undefined) {
+    if (Component !== undefined) {
+      return (
+        <Component
+          value={field.value}
+          row={row ?? { [field.field]: field.value }}
+          column={{ field: field.field }}
+        />
+      );
+    }
+    // biome-ignore lint/suspicious/noConsole: dev-warning for a registry mismatch, mirrors DataTableCell's columnRenderer warning.
+    console.warn(`[kumiko] fieldRenderer "${componentName}" not registered`);
+  }
+  return <Text testId={`field-value-${field.field}`}>{stringValue(field.value)}</Text>;
+}
+
+// Read-only text for `type: "reference"` — resolves the referenced row's
+// label via the same lookup query as ReferenceInput's combobox, but shows
+// plain text instead of mounting an (unusable, disabled) combobox.
+function ReadOnlyReferenceValue({
+  field,
+  featureName,
+}: {
+  readonly field: EditFieldViewModel;
+  readonly featureName: string;
+}): ReactNode {
+  const { Text } = usePrimitives();
+  const refEntity = field.refEntity ?? "";
+  const refFeature = field.refFeature ?? featureName;
+  const labelField = field.refLabelField ?? "id";
+  const isMultiple = field.refMultiple === true;
+  const queryQn = `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
+  const queryResult = useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(queryQn, {
+    limit: REFERENCE_COMBOBOX_LIMIT,
+  });
+  const ids: readonly string[] = isMultiple
+    ? Array.isArray(field.value)
+      ? (field.value as readonly string[])
+      : []
+    : typeof field.value === "string" && field.value !== ""
+      ? [field.value]
+      : [];
+  if (ids.length === 0) return <Text testId={`field-value-${field.field}`}>—</Text>;
+  const rows = queryResult.data?.rows ?? [];
+  const labels = ids.map((id) => {
+    const row = rows.find((r) => String(r["id"] ?? "") === id);
+    return row !== undefined ? String(row[labelField] ?? id) : id;
+  });
+  return <Text testId={`field-value-${field.field}`}>{labels.join(", ")}</Text>;
+}
+
+// Field types whose read display already isn't a boxed "disabled input" look
+// (embedded/jsonb render as an info Banner, files/images as an unsupported-
+// type Banner) — `readOnlyDisplayText` doesn't cover these, they keep going
+// through `renderInput`'s existing Banner branch in text-display mode too.
+function isComplexFieldType(type: string): boolean {
+  return type === "embedded" || type === "jsonb" || type === "files" || type === "images";
+}
+
 // Dispatches field.type → Input-kind. Select threads options through
 // from the EditFieldViewModel (computeEditViewModel pulls them from
 // SelectFieldDef.options). Structural types without a widget (embedded,
@@ -592,3 +711,58 @@ function locatedValue(v: unknown): { at: string; tz: string; utc?: string } | ""
   }
   return "";
 }
+
+// Read-only text for a `field.readOnly` field without its own `renderer` —
+// per-type formatting that reuses the same value-shaping helpers as the
+// editable widgets above, so a text value and its would-be Input widget stay
+// derived from the identical parse (fw#2245). `type: "reference"` isn't
+// covered here — it needs a live label lookup, see ReadOnlyReferenceValue.
+// `isComplexFieldType` types aren't covered either — callers keep those on
+// `renderInput`'s existing Banner fallback.
+function readOnlyDisplayText(field: EditFieldViewModel, appLocale: string): string {
+  const { type, value } = field;
+  if (value === undefined || value === null || value === "") return "—";
+  switch (type) {
+    case "boolean":
+      return applyFormatSpec({ format: "boolean" }, value);
+    case "date":
+      return applyFormatSpec({ format: "date", locale: field.dateLocale ?? appLocale }, value);
+    case "timestamp":
+      return applyFormatSpec({ format: "timestamp", locale: field.dateLocale ?? appLocale }, value);
+    case "locatedTimestamp": {
+      const located = locatedValue(value);
+      if (located === "" || located.at === "") return "—";
+      return applyFormatSpec(
+        { format: "timestamp", locale: field.dateLocale ?? appLocale },
+        located.utc ?? located.at,
+      );
+    }
+    case "number":
+    case "bigInt":
+    case "decimal": {
+      const n = numberValue(value);
+      return n === "" ? "—" : new Intl.NumberFormat(appLocale).format(n);
+    }
+    case "money": {
+      const currency = field.currency ?? "EUR";
+      const minor = moneyMinorValue(value, currency);
+      if (minor === "") return "—";
+      const major = minor / 10 ** currencyDecimals(currency);
+      return new Intl.NumberFormat(appLocale, { style: "currency", currency }).format(major);
+    }
+    case "select":
+    case "multiSelect": {
+      const labels = field.optionLabels;
+      const values = Array.isArray(value) ? value : [value];
+      if (values.length === 0) return "—";
+      return values
+        .map((v) => (typeof v === "string" ? (labels?.[v] ?? v) : stringValue(v)))
+        .join(", ");
+    }
+    case "file":
+    case "image":
+      return typeof value === "string" ? value : "—";
+    default:
+      return stringValue(value);
+  }
+}

package/src/index.ts

@@ -176,6 +176,7 @@ export type {
   DataTableSort,
   DataTableSortDir,
   DialogProps,
+  DrawerProps,
   EmbeddedListCellType,
   EmbeddedListColumn,
   EmbeddedListInputProps,

package/src/primitives.tsx

@@ -817,6 +817,20 @@ export type ModalProps = {
   readonly testId?: string;
 };
 
+/** Side panel for hosting an existing self-contained form/widget (own
+ *  submit/cancel buttons) without leaving the underlying screen — e.g. a
+ *  toolbar action's `kind: "drawer"` mounts an actionForm here instead of
+ *  navigating to a full page (fw#2225). Same "bare content shell, no
+ *  footer buttons of its own" contract as `Modal`, slide-in instead of
+ *  centered overlay. */
+export type DrawerProps = {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  readonly title?: string;
+  readonly children: ReactNode;
+  readonly testId?: string;
+};
+
 /** Image lightbox — full-size preview on click. Web renders Radix overlay;
  *  trigger (thumbnail) and open state live in the app. */
 export type LightboxProps = {
@@ -947,6 +961,10 @@ export type CorePrimitives = {
   readonly Heading: ComponentType<HeadingProps>;
   readonly Dialog: ComponentType<DialogProps>;
   readonly Modal: ComponentType<ModalProps>;
+  /** Optional (unlike the other Core-Primitives) so existing partial
+   *  CorePrimitives mocks in tests keep compiling — additive rollout of
+   *  a new primitive shouldn't force every test double to grow a stub. */
+  readonly Drawer?: ComponentType<DrawerProps>;
   readonly Lightbox: ComponentType<LightboxProps>;
   readonly ConfigSourceBadge: ComponentType<ConfigSourceBadgeProps>;
   readonly ConfigCascadeView: ComponentType<ConfigCascadeViewProps>;