@cosmicdrift/kumiko-renderer 0.332.0 → 0.333.0

package/dist/app/facet-count-bridge.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from "react";
+export type FacetCountQuery = {
+    readonly key: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+};
+export declare function FacetCountBridges({ queryType, queries, onCount, }: {
+    readonly queryType: string;
+    readonly queries: readonly FacetCountQuery[];
+    readonly onCount: (key: string, count: number) => void;
+}): ReactNode;

package/dist/app/facet-count-bridge.js

@@ -0,0 +1,20 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+// One invisible bridge per facet chip, mirroring ReferenceFacetBridges — the
+// chip count varies per screen, so useQuery can't be called in a loop. Each
+// bridge asks the list query for a single row plus `total`.
+// ponytail: one extra list query per chip, refetched on every list
+// invalidation; a server-side facet-count handler replaces this if it hurts.
+import { useEffect } from "react";
+import { useQuery } from "../hooks/use-query.js";
+function FacetCountBridge({ countKey, queryType, payload, onCount, }) {
+    const result = useQuery(queryType, payload);
+    const total = result.data?.total;
+    useEffect(() => {
+        if (total !== undefined)
+            onCount(countKey, total);
+    }, [total, countKey, onCount]);
+    return null;
+}
+export function FacetCountBridges({ queryType, queries, onCount, }) {
+    return (_jsx(_Fragment, { children: queries.map((query) => (_jsx(FacetCountBridge, { countKey: query.key, queryType: queryType, payload: query.payload, onCount: onCount }, query.key))) }));
+}

package/dist/app/kumiko-screen.js

@@ -23,9 +23,10 @@ import { synthesizeConfigEditEntity, synthesizeConfigEditScreen } from "./config
 import { useCustomScreenComponent } from "./custom-screens.js";
 import { useDashboardBody } from "./dashboard-body.js";
 import { EntityListExpandedRow } from "./entity-list-expanded-row.js";
+import { FacetCountBridges } from "./facet-count-bridge.js";
 import { buildFormSchema } from "./form-schema.js";
 import { layoutFieldNames } from "./layout-fields.js";
-import { buildDateRangePayload, buildFilterFacets, buildFilterPayload, clampDateRange, mergeReferenceFacetOptions, readDateRange, resolveDateRangeFacets, resolveProjectionFacetSpecs, } from "./list-facets.js";
+import { buildDateRangePayload, buildEntityFilterFacets, buildFacetCountRequests, buildFilterFacets, buildFilterPayload, clampDateRange, mergeReferenceFacetOptions, normalizeDefaultFilters, readDateRange, resolveDateRangeFacets, resolveProjectionFacetSpecs, } from "./list-facets.js";
 import { useInitialValuesHandoff, useNav } from "./nav.js";
 import { synthesizeProjectionDetailEntity, synthesizeProjectionDetailScreen, } from "./projection-detail-shim.js";
 import { synthesizeProjectionEntity, synthesizeProjectionScreen } from "./projection-list-shim.js";
@@ -319,10 +320,13 @@ function formatSummaryValue(value, locale) {
     }
     return value === null || value === undefined ? "" : String(value);
 }
+function formatSummaryParams(prefill, locale) {
+    return Object.fromEntries(Object.entries(prefill ?? {}).map(([name, value]) => [name, formatSummaryValue(value, locale)]));
+}
 function resolveActionFormSummary(summary, prefill, translate, locale) {
     if (summary === undefined)
         return undefined;
-    const params = Object.fromEntries(Object.entries(prefill ?? {}).map(([name, value]) => [name, formatSummaryValue(value, locale)]));
+    const params = formatSummaryParams(prefill, locale);
     return {
         title: translate(summary.title, params),
         ...(summary.subtitle !== undefined && { subtitle: translate(summary.subtitle, params) }),
@@ -906,6 +910,7 @@ function DrawerHost({ schema, drawerAction, drawerScreen, drawerInitialValues, u
     const { Drawer, Banner, Text, Dialog } = usePrimitives();
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
+    const locale = useLocale().locale();
     const [hasUnsavedInput, setHasUnsavedInput] = useState(false);
     const [confirmDiscardOpen, setConfirmDiscardOpen] = useState(false);
     const closeAndReset = useCallback(() => {
@@ -937,10 +942,13 @@ function DrawerHost({ schema, drawerAction, drawerScreen, drawerInitialValues, u
     // "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);
+    const titleParams = formatSummaryParams(drawerInitialValues, locale);
     return (_jsxs(_Fragment, { children: [_jsx(Drawer, { open: true, onOpenChange: (open) => {
                     if (!open)
                         requestClose();
-                }, title: effectiveTranslate(drawerAction.label), testId: `toolbar-drawer-${drawerAction.id}`, children: _jsx(PageHeaderSlotAvailableProvider, { value: false, children: _jsx(InsideDrawerProvider, { value: true, children: drawerScreen === undefined ? (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-toolbar-drawer-not-found", children: ["Screen not found: ", _jsx(Text, { variant: "code", children: drawerAction.screen })] })) : !allowed ? (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-toolbar-drawer-access-denied", children: ["Access denied: ", _jsx(Text, { variant: "code", children: drawerAction.screen })] })) : (_jsx(ActionFormBody, { schema: schema, screen: drawerScreen, ...(translate !== undefined && { translate }), ...(drawerInitialValues !== undefined && {
+                }, title: effectiveTranslate(drawerAction.title ?? drawerAction.label, titleParams), ...(drawerAction.subtitle !== undefined && {
+                    subtitle: effectiveTranslate(drawerAction.subtitle, titleParams),
+                }), testId: `toolbar-drawer-${drawerAction.id}`, children: _jsx(PageHeaderSlotAvailableProvider, { value: false, children: _jsx(InsideDrawerProvider, { value: true, children: drawerScreen === undefined ? (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-toolbar-drawer-not-found", children: ["Screen not found: ", _jsx(Text, { variant: "code", children: drawerAction.screen })] })) : !allowed ? (_jsxs(Banner, { padded: true, variant: "error", testId: "kumiko-toolbar-drawer-access-denied", children: ["Access denied: ", _jsx(Text, { variant: "code", children: drawerAction.screen })] })) : (_jsx(ActionFormBody, { schema: schema, screen: drawerScreen, ...(translate !== undefined && { translate }), ...(drawerInitialValues !== undefined && {
                                 initialOverrides: drawerInitialValues,
                             }), onSuccess: () => {
                                 setHasUnsavedInput(false);
@@ -974,7 +982,8 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
     // damit zwei Lists auf derselben Route nicht über dieselben
     // Query-Keys streiten. Default-Sort aus der Screen-Def gewinnt nur
     // wenn URL keinen sort hat — Author-Default vs User-Choice.
-    const urlState = useListUrlState(screen.id);
+    const defaultFilters = useMemo(() => normalizeDefaultFilters(screen.defaultFilters), [screen.defaultFilters]);
+    const urlState = useListUrlState(screen.id, defaultFilters);
     const effectiveSort = urlState.sort ?? screen.defaultSort ?? null;
     const limit = urlState.pageSize ?? screen.pageSize ?? 50;
     const paginationMode = screen.pagination ?? "pages";
@@ -1109,7 +1118,30 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
     const entityFacetSpecs = useMemo(() => resolveEntityFacetSpecs(entity.fields, featureName, screen.entity, effectiveTranslate), [entity.fields, featureName, screen.entity, effectiveTranslate]);
     const [entityReferenceFacetOptions, setEntityReferenceFacetOptions] = useState({});
     const handleEntityFacetOptions = useCallback((field, options) => setEntityReferenceFacetOptions((prev) => prev[field] === options ? prev : { ...prev, [field]: options }), []);
-    const filterFacets = useMemo(() => buildFilterFacets(mergeReferenceFacetOptions(entityFacetSpecs, entityReferenceFacetOptions)), [entityFacetSpecs, entityReferenceFacetOptions]);
+    const [facetCounts, setFacetCounts] = useState({});
+    const handleFacetCount = useCallback((key, count) => setFacetCounts((prev) => (prev[key] === count ? prev : { ...prev, [key]: count })), []);
+    const filterFacets = useMemo(() => buildEntityFilterFacets(mergeReferenceFacetOptions(entityFacetSpecs, entityReferenceFacetOptions), screen.facets, effectiveTranslate, facetCounts), [entityFacetSpecs, entityReferenceFacetOptions, screen.facets, effectiveTranslate, facetCounts]);
+    const facetCountQueries = useMemo(() => buildFacetCountRequests(entityFacetSpecs, screen.facets, effectiveTranslate).map((request) => {
+        const filters = buildFilterPayload({ ...urlState.filters, [request.field]: request.values }, (field) => entity.fields[field]?.type);
+        return {
+            key: request.key,
+            payload: {
+                limit: 1,
+                totalCount: true,
+                ...(urlState.q !== "" && { search: urlState.q }),
+                ...(screen.filter !== undefined && { filter: screen.filter }),
+                ...(filters.length > 0 && { filters }),
+            },
+        };
+    }), [
+        entityFacetSpecs,
+        screen.facets,
+        screen.filter,
+        effectiveTranslate,
+        urlState.filters,
+        urlState.q,
+        entity.fields,
+    ]);
     // Soft-Dispatcher: in Tests die ohne DispatcherProvider mounten,
     // bleibt rowActions undefined statt zu crashen. Echte Apps haben
     // den Provider via createKumikoApp — wenn nicht, ist es vermutlich
@@ -1189,6 +1221,7 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
                     id: action.id,
                     label: effectiveTranslate(action.label),
                     ...(action.style !== undefined && { style: action.style }),
+                    ...(action.display !== undefined && { display: action.display }),
                     confirmRequired: false,
                     ...(navigateAction.rowClick === true && { rowClick: true }),
                     ...(actionIcon !== undefined && { icon: actionIcon }),
@@ -1206,6 +1239,7 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
                     id: action.id,
                     label: effectiveTranslate(action.label),
                     ...(action.style !== undefined && { style: action.style }),
+                    ...(action.display !== undefined && { display: action.display }),
                     confirmRequired: false,
                     ...(actionIcon !== undefined && { icon: actionIcon }),
                     onTrigger: (row) => {
@@ -1358,7 +1392,7 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
     // Bei Infinite-Mode: rows kommen aus accumulated (über mehrere
     // useQuery-Calls gesammelt), bei pages/false aus dem aktuellen Result.
     const renderRows = useInfinite ? accumulated : (rowsQuery.data?.rows ?? []);
-    return (_jsxs(_Fragment, { children: [_jsx(ReferenceFacetBridges, { specs: entityFacetSpecs, onOptions: handleEntityFacetOptions }), _jsx(RenderList, { screen: screen, entity: entity, rows: renderRows, featureName: featureName, searchable: searchable, searchValue: urlState.q, onSearchChange: urlState.setQ, sort: effectiveSort, onSortChange: urlState.setSort, screenPadding: true, ...(screenFillsHeight(screen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(toolbarActions !== undefined && toolbarActions.length > 0 && { toolbarActions }), ...(useInfinite && {
+    return (_jsxs(_Fragment, { children: [_jsx(ReferenceFacetBridges, { specs: entityFacetSpecs, onOptions: handleEntityFacetOptions }), _jsx(FacetCountBridges, { queryType: queryType, queries: facetCountQueries, onCount: handleFacetCount }), _jsx(RenderList, { screen: screen, entity: entity, rows: renderRows, featureName: featureName, searchable: searchable, searchValue: urlState.q, onSearchChange: urlState.setQ, sort: effectiveSort, onSortChange: urlState.setSort, screenPadding: true, ...(screenFillsHeight(screen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(screen.rowActionMode !== undefined && { rowActionMode: screen.rowActionMode }), ...(toolbarActions !== undefined && toolbarActions.length > 0 && { toolbarActions }), ...(useInfinite && {
                     onReachEnd: loadMore,
                     loadingMore: rowsQuery.loading,
                     hasMore,
@@ -1557,7 +1591,7 @@ function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
             onPageSizeChange: urlState.setPageSize,
         }
         : undefined;
-    return (_jsxs(_Fragment, { children: [_jsx(ReferenceFacetBridges, { specs: facetSpecs, onOptions: handleProjectionFacetOptions }), _jsx(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, screenPadding: true, ...(screenFillsHeight(listScreen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(toolbarActions !== undefined && { toolbarActions }), ...(translate !== undefined && { translate }), ...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick }), ...(filterFacets.length > 0 && {
+    return (_jsxs(_Fragment, { children: [_jsx(ReferenceFacetBridges, { specs: facetSpecs, onOptions: handleProjectionFacetOptions }), _jsx(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, screenPadding: true, ...(screenFillsHeight(listScreen) && { scrollBody: true }), ...(pager !== undefined && { pager }), ...(rowActions !== undefined && { rowActions }), ...(screen.rowActionMode !== undefined && { rowActionMode: screen.rowActionMode }), ...(toolbarActions !== undefined && { toolbarActions }), ...(translate !== undefined && { translate }), ...(wrappedOnRowClick !== undefined && { onRowClick: wrappedOnRowClick }), ...(filterFacets.length > 0 && {
                     filterFacets,
                     onFilterChange: urlState.setFilter,
                 }), ...(dateRangeFacets.length > 0 && {
@@ -2140,7 +2174,7 @@ function ActionFormBody({ schema, screen, translate, initialOverrides, onSuccess
         // sie Kontext ziehen könnten.
         extensionInitialValues: initial, writeCommand: screen.handler, payloadMode: "values", onSubmit: handleSubmitted, ...(handleCancel !== undefined && { onCancel: handleCancel }), ...(onDirtyChange !== undefined && { onDirtyChange }), ...((insideDrawer || screenFillsHeight(screen)) && { fillScreenHeight: true }), ...((screen.submitLabel ?? submitLabelFallback) !== undefined && {
             submitLabel: screen.submitLabel ?? submitLabelFallback,
-        }), ...(screen.submitStyle !== undefined && { submitVariant: screen.submitStyle }), ...(summary !== undefined && { summary }), ...(translate !== undefined && { translate }) }));
+        }), ...(screen.submitStyle !== undefined && { submitVariant: screen.submitStyle }), ...(screen.footerActions !== undefined && { footerActions: screen.footerActions }), ...(summary !== undefined && { summary }), ...(translate !== undefined && { translate }) }));
 }
 // A money-typed config-edit field renders through RenderField's entityEdit
 // `{amount, currency}` payload shape (render-field.tsx, #1923), but

package/dist/app/list-facets.d.ts

@@ -1,6 +1,6 @@
-import type { ListFacetSpec } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { EntityListFacetConfig, ListFacetSpec } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Translate } from "@cosmicdrift/kumiko-headless";
-import type { DataTableFacet } from "../primitives.js";
+import type { DataTableFacet, DataTableFacetChip } from "../primitives.js";
 export type ResolvedFacetSpec = {
     readonly field: string;
     readonly type: "select" | "boolean" | "reference";
@@ -24,6 +24,17 @@ export declare function mergeReferenceFacetOptions(specs: readonly ResolvedFacet
     readonly label: string;
 }[]>>): ResolvedFacetSpec[];
 export declare function buildFilterFacets(specs: readonly ResolvedFacetSpec[]): DataTableFacet[];
+type FacetConfigByField = Readonly<Record<string, EntityListFacetConfig | false>>;
+export declare function buildFacetChips(spec: ResolvedFacetSpec, config: EntityListFacetConfig, translate: Translate): DataTableFacetChip[];
+export declare function buildEntityFilterFacets(specs: readonly ResolvedFacetSpec[], configs: FacetConfigByField | undefined, translate: Translate, counts: Readonly<Record<string, number>>): DataTableFacet[];
+export declare function facetCountKey(field: string, chipId: string): string;
+export type FacetCountRequest = {
+    readonly key: string;
+    readonly field: string;
+    readonly values: readonly string[];
+};
+export declare function buildFacetCountRequests(specs: readonly ResolvedFacetSpec[], configs: FacetConfigByField | undefined, translate: Translate): FacetCountRequest[];
+export declare function normalizeDefaultFilters(defaults: Readonly<Record<string, readonly string[] | boolean>> | undefined): Readonly<Record<string, readonly string[]>>;
 export declare function buildFilterPayload(urlFilters: Readonly<Record<string, readonly string[]>>, typeOf: (field: string) => string | undefined): {
     field: string;
     op: "in";
@@ -46,3 +57,4 @@ export declare function dateRangeUrlField(field: string, bound: DateRangeBound):
 export declare function readDateRange(urlFilters: Readonly<Record<string, readonly string[]>>, field: string): DateRangeValue;
 export declare function clampDateRange(current: DateRangeValue, bound: DateRangeBound, value: string): DateRangeValue;
 export declare function buildDateRangePayload(specs: readonly ResolvedDateRangeFacet[], urlFilters: Readonly<Record<string, readonly string[]>>, timeZone: string): Record<string, string>;
+export {};

package/dist/app/list-facets.js

@@ -12,6 +12,80 @@ export function mergeReferenceFacetOptions(specs, optionsByField) {
 export function buildFilterFacets(specs) {
     return specs.map((spec) => ({ field: spec.field, label: spec.label, options: spec.options }));
 }
+// Chips are the field's own options plus the declared extra choices
+// ("Running" bundle, "All"), in the order the config's `position` asks for.
+export function buildFacetChips(spec, config, translate) {
+    const extras = config.extraOptions ?? [];
+    const toChip = (extra) => ({
+        id: extra.id,
+        label: translate(extra.label),
+        values: extra.values,
+    });
+    return [
+        ...extras.filter((extra) => extra.position !== "end").map(toChip),
+        ...spec.options.map((option) => ({
+            id: option.value,
+            label: option.label,
+            values: [option.value],
+        })),
+        ...extras.filter((extra) => extra.position === "end").map(toChip),
+    ];
+}
+// entityList facet controls: `false` drops the control, `display: "chips"`
+// turns it into toggle chips; counts (when requested) are merged in by chip.
+export function buildEntityFilterFacets(specs, configs, translate, counts) {
+    const out = [];
+    for (const spec of specs) {
+        const config = configs?.[spec.field];
+        if (config === false)
+            continue;
+        const base = { field: spec.field, label: spec.label, options: spec.options };
+        if (config?.display !== "chips") {
+            out.push(base);
+            continue;
+        }
+        out.push({
+            ...base,
+            chips: buildFacetChips(spec, config, translate).map((chip) => {
+                const count = counts[facetCountKey(spec.field, chip.id)];
+                return count === undefined ? chip : { ...chip, count };
+            }),
+            ...(config.showCounts === true && { showCounts: true }),
+            ...(config.hideEmpty === true && { hideEmpty: true }),
+        });
+    }
+    return out;
+}
+export function facetCountKey(field, chipId) {
+    return `${field}\u0000${chipId}`;
+}
+// One count request per chip of a facet that shows counts or hides empty
+// chips. The chip's own values replace that facet's selection; other facets
+// keep theirs.
+export function buildFacetCountRequests(specs, configs, translate) {
+    const out = [];
+    for (const spec of specs) {
+        const config = configs?.[spec.field];
+        if (config === undefined || config === false || config.display !== "chips")
+            continue;
+        if (config.showCounts !== true && config.hideEmpty !== true)
+            continue;
+        for (const chip of buildFacetChips(spec, config, translate)) {
+            out.push({ key: facetCountKey(spec.field, chip.id), field: spec.field, values: chip.values });
+        }
+    }
+    return out;
+}
+// `defaultFilters` values are option values or a boolean; the URL-state shape
+// is string[] (booleans as "true"/"false", like buildFilterPayload expects).
+export function normalizeDefaultFilters(defaults) {
+    if (defaults === undefined)
+        return {};
+    return Object.fromEntries(Object.entries(defaults).map(([field, value]) => [
+        field,
+        typeof value === "boolean" ? [String(value)] : value,
+    ]));
+}
 // 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

package/dist/app/row-actions.js

@@ -93,6 +93,7 @@ function buildNavigateRowAction(action, translate, nav, host) {
         id: action.id,
         label: translate(action.label),
         ...(action.style !== undefined && { style: action.style }),
+        ...(action.display !== undefined && { display: action.display }),
         confirmRequired: false,
         ...(action.rowClick === true && { rowClick: true }),
         ...(actionIcon !== undefined && { icon: actionIcon }),
@@ -125,6 +126,7 @@ function buildDrawerRowAction(action, translate, openDrawer) {
         id: action.id,
         label: translate(action.label),
         ...(action.style !== undefined && { style: action.style }),
+        ...(action.display !== undefined && { display: action.display }),
         confirmRequired: false,
         ...(actionIcon !== undefined && { icon: actionIcon }),
         onTrigger: (row) => {
@@ -149,6 +151,7 @@ function buildWriteHandlerRowAction(action, translate, refetch, dispatcher) {
         id: action.id,
         label: translate(action.label),
         ...(action.style !== undefined && { style: action.style }),
+        ...(action.display !== undefined && { display: action.display }),
         icon: resolveActionIcon(action.id, action.icon),
         ...(action.confirm !== undefined && { confirm: translate(action.confirm) }),
         ...(action.confirmLabel !== undefined && {
@@ -290,47 +293,52 @@ export function buildProjectionToolbarActions(options) {
     }
     return out.length > 0 ? out : undefined;
 }
-function buildNavigateRecordAction(action, options) {
-    const { record, translate, nav, host, actionIcon, defaultScreenTargetEntityId, sameEntityScreenId, } = options;
-    if (action.entity !== undefined) {
-        const targetEntity = action.entity;
-        const id = action.entityId !== undefined ? String(record[action.entityId] ?? "") : "";
-        return {
-            id: action.id,
-            label: translate(action.label),
-            ...(action.style !== undefined && { style: action.style }),
-            confirmRequired: false,
-            ...(actionIcon !== undefined && { icon: actionIcon }),
-            onPress: () => {
-                // No entityId on record (id === "") → nothing to navigate to.
-                if (id !== "") {
-                    const params = navigateActionSearchParams(action, record);
-                    navigateWithReturnTo(nav, { entity: targetEntity, id }, host, params);
-                }
-            },
-        };
-    }
-    if (action.screen !== undefined) {
-        const explicit = action.entityId !== undefined ? String(record[action.entityId] ?? "") : undefined;
-        const fallback = sameEntityScreenId?.(action.screen) ?? defaultScreenTargetEntityId;
-        const navEntityId = explicit ?? fallback;
-        const targetScreen = action.screen;
-        return {
-            id: action.id,
-            label: translate(action.label),
-            ...(action.style !== undefined && { style: action.style }),
-            confirmRequired: false,
-            ...(actionIcon !== undefined && { icon: actionIcon }),
-            onPress: () => {
-                const target = {
-                    screenId: targetScreen,
-                    ...(navEntityId !== undefined && navEntityId !== "" && { entityId: navEntityId }),
-                };
+function navigateActionBase(action, translate, actionIcon) {
+    return {
+        id: action.id,
+        label: translate(action.label),
+        ...(action.style !== undefined && { style: action.style }),
+        ...(action.display !== undefined && { display: action.display }),
+        confirmRequired: false,
+        ...(actionIcon !== undefined && { icon: actionIcon }),
+    };
+}
+function buildNavigateEntityAction(action, targetEntity, options) {
+    const { record, translate, nav, host, actionIcon } = options;
+    const id = action.entityId !== undefined ? String(record[action.entityId] ?? "") : "";
+    return {
+        ...navigateActionBase(action, translate, actionIcon),
+        onPress: () => {
+            // No entityId on record (id === "") → nothing to navigate to.
+            if (id !== "") {
                 const params = navigateActionSearchParams(action, record);
-                navigateWithReturnTo(nav, target, host, params);
-            },
-        };
-    }
+                navigateWithReturnTo(nav, { entity: targetEntity, id }, host, params);
+            }
+        },
+    };
+}
+function buildNavigateScreenAction(action, targetScreen, options) {
+    const { record, translate, nav, host, actionIcon, defaultScreenTargetEntityId, sameEntityScreenId, } = options;
+    const explicit = action.entityId !== undefined ? String(record[action.entityId] ?? "") : undefined;
+    const fallback = sameEntityScreenId?.(targetScreen) ?? defaultScreenTargetEntityId;
+    const navEntityId = explicit ?? fallback;
+    return {
+        ...navigateActionBase(action, translate, actionIcon),
+        onPress: () => {
+            const target = {
+                screenId: targetScreen,
+                ...(navEntityId !== undefined && navEntityId !== "" && { entityId: navEntityId }),
+            };
+            const params = navigateActionSearchParams(action, record);
+            navigateWithReturnTo(nav, target, host, params);
+        },
+    };
+}
+function buildNavigateRecordAction(action, options) {
+    if (action.entity !== undefined)
+        return buildNavigateEntityAction(action, action.entity, options);
+    if (action.screen !== undefined)
+        return buildNavigateScreenAction(action, action.screen, options);
     return undefined;
 }
 function buildDrawerRecordAction(action, options) {
@@ -339,6 +347,7 @@ function buildDrawerRecordAction(action, options) {
         id: action.id,
         label: translate(action.label),
         ...(action.style !== undefined && { style: action.style }),
+        ...(action.display !== undefined && { display: action.display }),
         confirmRequired: false,
         ...(actionIcon !== undefined && { icon: actionIcon }),
         onPress: () => {
@@ -353,6 +362,7 @@ function buildWriteHandlerRecordAction(action, options) {
         id: action.id,
         label: translate(action.label),
         ...(action.style !== undefined && { style: action.style }),
+        ...(action.display !== undefined && { display: action.display }),
         ...(actionIcon !== undefined && { icon: actionIcon }),
         ...(action.confirm !== undefined && { confirm: translate(action.confirm) }),
         ...(action.confirmLabel !== undefined && {

package/dist/components/related-list-section.js

@@ -1,5 +1,5 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { normalizeListColumn, parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
+import { evalFieldCondition, normalizeListColumn, parseRefTarget, } from "@cosmicdrift/kumiko-framework/ui-types";
 import { useCallback, useMemo, useState } from "react";
 import { useAppFeatures } from "../app/app-features-context.js";
 import { buildFilterFacets, buildFilterPayload, mergeReferenceFacetOptions, resolveProjectionFacetSpecs, } from "../app/list-facets.js";
@@ -12,9 +12,9 @@ import { dispatcherErrorText } from "../app/write-failed-error.js";
 import { useOptionalDispatcher } from "../context/dispatcher-context.js";
 import { useUserRoles } from "../context/user-roles-context.js";
 import { useQuery } from "../hooks/use-query.js";
-import { useTranslation } from "../i18n.js";
+import { useLocale, useTranslation } from "../i18n.js";
 import { PageHeaderSlotAvailableProvider } from "../page-header-slot.js";
-import { usePrimitives } from "../primitives.js";
+import { usePrimitives, } from "../primitives.js";
 import { sortByAccessor } from "../sort-by-accessor.js";
 import { RenderEditActionButton } from "./render-edit-action-button.js";
 import { RenderList } from "./render-list.js";
@@ -47,11 +47,48 @@ function warnRelatedListEmptyStateDrawerDropped(actionId) {
     // biome-ignore lint/suspicious/noConsole: dev-time warning, same pattern as row-actions.ts
     console.warn(`[kumiko] relatedList emptyState.action "${actionId}" is kind: "drawer" but no onOpenDrawer was supplied — dropped.`);
 }
+function buildRowGrouping(groupBy, translate, locale) {
+    return {
+        keyOf: (row) => String(row.values[groupBy.field] ?? ""),
+        startsCollapsed: (key) => groupBy.collapsedWhen !== undefined && key === String(groupBy.collapsedWhen),
+        headerLabel: (key, rows) => {
+            const dates = groupBy.dateField === undefined
+                ? []
+                : rows
+                    .map((row) => String(row.values[groupBy.dateField ?? ""] ?? ""))
+                    .filter((value) => value !== "")
+                    .sort();
+            const latest = dates[dates.length - 1];
+            return translate(groupBy.labels?.[key] ?? groupBy.label, {
+                count: rows.length,
+                value: key,
+                lastDate: latest === undefined
+                    ? ""
+                    : new Date(latest).toLocaleDateString(locale, {
+                        year: "numeric",
+                        month: "2-digit",
+                        day: "2-digit",
+                        timeZone: "UTC",
+                    }),
+            });
+        },
+    };
+}
+function buildRowTone(rule) {
+    if (rule === undefined)
+        return undefined;
+    return (row) => (evalFieldCondition(rule, { ...row.values }) ? rule.tone : undefined);
+}
 export function RelatedListSection({ section, parentId, record, featureName, translate, hideTitle, grow, onOpenDrawer, actions, embedded, onAfterWrite, }) {
     const { Banner, Section, Card, FillContainer, Text, Button, Dialog } = usePrimitives();
     const [emptyStateActionError, setEmptyStateActionError] = useState(null);
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
+    const locale = useLocale().locale();
+    const rowGrouping = useMemo(() => section.groupBy === undefined
+        ? undefined
+        : buildRowGrouping(section.groupBy, effectiveTranslate, locale), [section.groupBy, effectiveTranslate, locale]);
+    const rowTone = useMemo(() => buildRowTone(section.rowTone), [section.rowTone]);
     const nav = useNav();
     const host = useReturnHost();
     const dispatcher = useOptionalDispatcher();
@@ -269,7 +306,7 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
                         filterValues: filters,
                         onFilterChange,
                         onFilterReset,
-                    }), ...(onRowClick !== undefined && { onRowClick }), ...(rowActions !== undefined && { rowActions }), ...(toolbarActionButtons !== undefined && { toolbarActions: toolbarActionButtons }), ...(emptyStateContent !== undefined && { emptyState: emptyStateContent }), ...(hideTitle === true && {
+                    }), ...(onRowClick !== undefined && { onRowClick }), ...(rowActions !== undefined && { rowActions }), ...(section.rowActionMode !== undefined && { rowActionMode: section.rowActionMode }), ...(rowGrouping !== undefined && { rowGrouping }), ...(rowTone !== undefined && { rowTone }), ...(toolbarActionButtons !== undefined && { toolbarActions: toolbarActionButtons }), ...(emptyStateContent !== undefined && { emptyState: emptyStateContent }), ...(hideTitle === true && {
                         scrollBody: true,
                         screenPadding: false,
                         chromeless: true,

package/dist/components/render-edit-types.d.ts

@@ -1,4 +1,4 @@
-import type { EntityDefinition, EntityEditScreenDefinition, IconKey, RowAction, RowActionDrawer } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ActionFormFooterAction, EntityDefinition, EntityEditScreenDefinition, IconKey, RowAction, RowActionDrawer } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { DispatcherError, FormSnapshot, FormValues, SubmitResult, Translate } from "@cosmicdrift/kumiko-headless";
 import type { ReactNode } from "react";
 import type * as z from "zod";
@@ -73,6 +73,9 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
     readonly submitLabel?: string;
     /** Visual style of the submit button (actionForm `submitStyle`). Default "primary". */
     readonly submitVariant?: "primary" | "danger";
+    /** Extra footer buttons (actionForm `footerActions`): each sets its `patch`
+     *  on the form values, then submits through the normal validate + write path. */
+    readonly footerActions?: readonly ActionFormFooterAction[];
     /** Context box above the drawer form (title + optional subtitle, already resolved). */
     readonly summary?: {
         readonly title: string;

package/dist/components/render-edit.js

@@ -6,6 +6,7 @@ import { AllFieldsRequiredProvider } from "./render-field.js";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { ExtensionFormRegistryProvider, useExtensionFormHost, } from "../app/extension-form-submit.js";
 import { extensionSectionName, useExtensionSectionComponent } from "../app/extension-sections.js";
+import { layoutEditFields } from "../app/layout-fields.js";
 import { useOptionalDispatcher } from "../context/dispatcher-context.js";
 import { useDraftStorage } from "../context/draft-storage-context.js";
 import { formatWhen } from "../format-when.js";
@@ -145,8 +146,23 @@ function formSectionDomId(sectionIndex) {
 export function resolveRecordTitle(value) {
     return typeof value === "string" && value.trim() !== "" ? value : undefined;
 }
+const TITLE_PLACEHOLDER_PATTERN = /\{(\w+)\}/g;
+// Falls back to the plain title while any placeholder value is still empty,
+// so the header never shows "Add  " mid-typing.
+function resolveTitleTemplate(template, values, translate, fallback) {
+    if (template === undefined)
+        return fallback;
+    const placeholders = [...translate(template).matchAll(TITLE_PLACEHOLDER_PATTERN)].map((match) => match[1] ?? "");
+    const isFilled = (name) => {
+        const value = values[name];
+        return value !== undefined && value !== null && String(value).trim() !== "";
+    };
+    if (!placeholders.every(isFilled))
+        return fallback;
+    return translate(template, values);
+}
 export function RenderEdit(props) {
-    const { screen, entity, featureName, initial, writeCommand, translate: translateProp, ctx, schema, onSubmit, payloadMode = "values", buildPayload, serverFieldPathPrefix, onDelete, onCancel, onReload, onDirtyChange, onCopyLink, actions, onRelatedListDrawerAction, submitLabel, submitVariant, summary, labelAppendix, fieldAppendix, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, headerRegion, buildSectionActions, } = props;
+    const { screen, entity, featureName, initial, writeCommand, translate: translateProp, ctx, schema, onSubmit, payloadMode = "values", buildPayload, serverFieldPathPrefix, onDelete, onCancel, onReload, onDirtyChange, onCopyLink, actions, onRelatedListDrawerAction, submitLabel, submitVariant, footerActions, summary, labelAppendix, fieldAppendix, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, headerRegion, buildSectionActions, } = props;
     const { customSubmit } = props;
     // Translate-Fallback: wenn der Caller keine Translate-Fn übergibt,
     // konsumieren wir den i18next-Context direkt. Sonst wären Field-
@@ -239,11 +255,15 @@ export function RenderEdit(props) {
     // Submit-Config nur wenn der Caller einen writeCommand mitgibt; bei
     // customSubmit-Pfad kommt der Form-Controller ohne Submit-Wiring,
     // weil wir controller.submit() eh nicht rufen.
+    const omitFields = useMemo(() => layoutEditFields(screen)
+        .filter((spec) => spec.submit === false)
+        .map((spec) => spec.field), [screen]);
     const submitConfig = writeCommand !== undefined
         ? {
             type: writeCommand,
             payloadMode,
             ...(buildPayload !== undefined && { buildPayload }),
+            ...(omitFields.length > 0 && { omitFields }),
             ...(serverFieldPathPrefix !== undefined && { serverFieldPathPrefix }),
             ...(scopeFieldNames !== undefined && { validateScope: scopeFieldNames }),
         }
@@ -944,7 +964,12 @@ export function RenderEdit(props) {
     const nextStepTitle = isWizard ? filteredSections[currentStep + 1]?.title : undefined;
     const formActions = (_jsxs(_Fragment, { children: [isWizard && currentStep > 0 && (_jsx(Button, { type: "button", variant: "secondary", icon: "chevron-left", onClick: handleWizardBack, testId: "render-edit-wizard-back", children: translate("kumiko.actions.back") })), footerSlot !== undefined && (_jsx(EditSlotMount, { slot: footerSlot, slotName: "footer", screenId: screen.id, entityName: vm.entityName, entityId: resolveExtensionEntityId(entityIdProp, vm.id), values: snapshot.values, hasUnsavedChanges: snapshot.isDirty || extensionDirty, wizardStep: isWizard ? { index: currentStep, isLast: isLastWizardStep } : undefined, ...(screen.slots?.footerPrimary === true && { [STICKY_PRIMARY_ACTION_PROP]: true }) })), isWizard && !isLastWizardStep && showsSubmit && !isCreateMode && (_jsx(Button, { type: "button", variant: "ghost", disabled: isSubmitting || disabled, onClick: () => void handleSubmit({ saveNow: true }), testId: "render-edit-wizard-save-close", [STICKY_PRIMARY_ACTION_PROP]: true, children: translate("kumiko.wizard.save-and-close") })), isWizard && !isLastWizardStep && (_jsx(Button, { type: "submit", variant: "primary", iconEnd: "chevron-right", testId: "render-edit-wizard-next", children: nextStepTitle !== undefined
                     ? translate("kumiko.wizard.next-with-title", { title: nextStepTitle })
-                    : translate("kumiko.actions.next") })), showsSubmit && (!isWizard || isLastWizardStep) && (_jsx(Button, { type: "submit", disabled: (snapshot.isUnchanged && !extensionDirty && !isFieldless && !insideDrawer) ||
+                    : translate("kumiko.actions.next") })), showsSubmit &&
+                (!isWizard || isLastWizardStep) &&
+                footerActions?.map((action) => (_jsx(Button, { type: "button", variant: action.variant ?? "secondary", ...(action.icon !== undefined && { icon: action.icon }), disabled: isSubmitting || disabled, onClick: () => {
+                        controller.setValues(action.patch); // @cast-boundary form-values
+                        void handleSubmit();
+                    }, testId: `render-edit-footer-action-${action.id}`, children: translate(action.label) }, action.id))), showsSubmit && (!isWizard || isLastWizardStep) && (_jsx(Button, { type: "submit", disabled: (snapshot.isUnchanged && !extensionDirty && !isFieldless && !insideDrawer) ||
                     isSubmitting ||
                     disabled, loading: isSubmitting, variant: submitVariant ?? "primary", testId: "render-edit-submit", children: translate(submitLabel ?? (isWizard ? "kumiko.actions.finish" : "kumiko.actions.save")) }))] }));
     // Title + Subtitle, create/edit-bewusst. i18n-Keys (mode = "create"|"edit"):
@@ -976,7 +1001,8 @@ export function RenderEdit(props) {
         }
         return undefined;
     };
-    const formTitle = resolveScreenText("title") ?? screen.id;
+    const plainFormTitle = resolveScreenText("title") ?? screen.id;
+    const formTitle = resolveTitleTemplate(screen.titleTemplate, snapshot.values, translate, plainFormTitle);
     // screen.description is head-card copy, not tab content — in tabs mode
     // (hideSectionTitles) the head card already carries title/subtitle/status.
     const formSubtitle = hideSectionTitles !== true
@@ -986,6 +1012,7 @@ export function RenderEdit(props) {
     const usesFieldFlow = isScreenForm || insideDrawer;
     const allRequiredHint = (_jsx(Text, { variant: "muted", testId: "render-edit-all-required-hint", children: translate("kumiko.form.all-required") }));
     const stepRail = isWizard && isScreenForm && StepBar !== undefined;
+    const upNextSection = screen.layout.wizard?.aside?.upNext === true ? filteredSections[currentStep + 1] : undefined;
     const changedFieldCount = isCreate ? 0 : Object.keys(snapshot.changes).length;
     const unsavedCount = isCreate || !isScreenForm
         ? 0
@@ -1023,7 +1050,14 @@ export function RenderEdit(props) {
                     sideRail: (_jsx(StepBar, { steps: filteredSections.map((section) => section.title ?? ""), currentIndex: currentStep, compactLabel: compactStepLabel, onStepSelect: handleWizardJumpBack, orientation: "vertical", heading: translate("kumiko.wizard.step", {
                             current: currentStep + 1,
                             total: lastStepIndex + 1,
-                        }), ...(formSubtitle !== undefined && { description: formSubtitle }), testId: "render-edit-wizard-steps", compactTestId: "render-edit-wizard-step-label" })),
+                        }), ...(formSubtitle !== undefined && { description: formSubtitle }), subtitles: filteredSections.map((section) => section.kind === "fields" ? section.subtitle : undefined), ...(upNextSection !== undefined && {
+                            upNext: {
+                                heading: translate("kumiko.wizard.up-next"),
+                                title: upNextSection.title ?? "",
+                                ...(upNextSection.kind === "fields" &&
+                                    upNextSection.subtitle !== undefined && { subtitle: upNextSection.subtitle }),
+                            },
+                        }), testId: "render-edit-wizard-steps", compactTestId: "render-edit-wizard-step-label" })),
                 }), ...(hideActions !== true && hasFormActions && { actions: formActions }), ...(hideActions !== true &&
                     hasSecondaryFormActions && { secondaryActions: secondaryFormActions }), testId: "render-edit-form", stickyActions: isWizard || fillScreenHeight === true, ...(screen.layout.width !== undefined && { width: screen.layout.width }), ...(formHeaderRegion !== undefined && { headerRegion: formHeaderRegion }), ...(titleActionMount !== undefined && { titleAction: titleActionMount }), ...(fillHeight && { fillHeight }), ...(hideSectionTitles === true && { chromeless: true }), ...(summary !== undefined && { summary }), children: _jsxs(AllFieldsRequiredProvider, { value: showsAllRequiredHint, children: [showsAllRequiredHint && !insideDrawer && allRequiredHint, draftCandidates !== null && (_jsx(Banner, { variant: "info", testId: "render-edit-draft-picker", actions: [
                                 ...draftCandidates.map((candidate) => (_jsx(Button, { type: "button", variant: "link", onClick: () => adoptDraft(candidate), testId: `render-edit-draft-pick-${candidate.id}`, children: formatWhen(candidate.savedAt) }, candidate.id))),

package/dist/components/render-list.d.ts

@@ -2,7 +2,7 @@ import type { EntityDefinition, EntityListScreenDefinition, IconKey } from "@cos
 import type { ListRowViewModel, Translate } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode } from "react";
 import type { ListSort } from "../hooks/use-list-url-state.js";
-import { type DataTableDateRangeFacet, type DataTableFacet, type DataTableRowAction, type DataTableRowActionMode } from "../primitives.js";
+import { type DataTableDateRangeFacet, type DataTableFacet, type DataTableProps, type DataTableRowAction, type DataTableRowActionMode, type DataTableRowGrouping } from "../primitives.js";
 export type RenderListProps = {
     readonly screen: EntityListScreenDefinition;
     readonly entity: EntityDefinition;
@@ -65,6 +65,9 @@ export type RenderListProps = {
      *  KumikoScreen derives it from the actions themselves; without it the
      *  DataTable falls back to its adaptive default. */
     readonly rowActionMode?: DataTableRowActionMode;
+    /** Forwarded to `DataTableProps.rowGrouping` / `rowTone`. */
+    readonly rowGrouping?: DataTableRowGrouping;
+    readonly rowTone?: DataTableProps["rowTone"];
     /** Toolbar-Aktionen im List-Header — Resolved-Form (KumikoScreen baut
      *  das aus EntityListScreenDefinition.toolbarActions: navigate-target
      *  → useNav, handler-QN → dispatcher-Call). RenderList rendert die

package/dist/components/render-list.js

@@ -13,7 +13,7 @@ function isHeaderPromotableToolbarAction(action) {
     return (action.style === "primary" && action.confirm === undefined && action.confirmRequired === false);
 }
 export function RenderList(props) {
-    const { screen, entity, rows, featureName, translate: translateProp, onRowClick, emptyState, onCreate, createLabel, searchable = false, searchPlaceholder, description, itemNounKey, searchValue, onSearchChange, sort, onSortChange, pager, onReachEnd, loadingMore, hasMore, rowActions, rowActionMode, toolbarActions, filterFacets, filterValues, onFilterChange, onFilterReset, dateRangeFacets, onDateRangeChange, chromeless, scrollBody, screenPadding, expandedRowIds, onToggleRowExpanded, renderExpandedRow, } = props;
+    const { screen, entity, rows, featureName, translate: translateProp, onRowClick, emptyState, onCreate, createLabel, searchable = false, searchPlaceholder, description, itemNounKey, searchValue, onSearchChange, sort, onSortChange, pager, onReachEnd, loadingMore, hasMore, rowActions, rowActionMode, rowGrouping, rowTone, toolbarActions, filterFacets, filterValues, onFilterChange, onFilterReset, dateRangeFacets, onDateRangeChange, chromeless, scrollBody, screenPadding, expandedRowIds, onToggleRowExpanded, renderExpandedRow, } = props;
     // Wie RenderEdit: Translate-Fallback aus dem i18next-Context, sonst
     // wären Column-Header raw i18n-Keys.
     const t = useTranslation();
@@ -168,7 +168,7 @@ export function RenderList(props) {
     const resolvedTitle = translate(titleKey);
     const toolbarTitle = resolvedTitle === titleKey ? screen.id : resolvedTitle;
     // ListSort = DataTableSort (use-list-url-state aliased) — kein Cast nötig.
-    return (_jsxs(_Fragment, { children: [createInPageHeader && PageHeader !== undefined && _jsx(PageHeader, { actions: createButton }), promotedActionButton !== undefined && PageHeader !== undefined && (_jsx(PageHeader, { actions: promotedActionButton })), referenceColumns.map((rc) => (_jsx(ReferenceLookupBridge, { field: rc.field, refEntity: rc.refEntity, labelField: rc.labelField, featureName: rc.refFeature, onMap: handleLookupMap }, rc.field))), _jsx(DataTable, { columns: enrichedVm.columns, rows: enrichedVm.rows, toolbarTitle: toolbarTitle, ...(onRowClick !== undefined && { onRowClick }), ...(composedEmptyState !== undefined && { emptyState: composedEmptyState }), ...(toolbarStart !== undefined && { toolbarStart }), ...(description !== undefined && !searchable && { toolbarDescription: description }), ...(toolbarEnd !== undefined && { toolbarEnd }), ...(sort !== undefined && { sort }), ...(onSortChange !== undefined && { onSortChange }), ...(pager !== undefined && { pager }), ...(onReachEnd !== undefined && { onReachEnd }), ...(loadingMore !== undefined && { loadingMore }), ...(hasMore !== undefined && { hasMore }), ...(itemNoun !== undefined && { itemNoun }), ...(rowActions !== undefined && { rowActions }), ...(rowActionMode !== undefined && { rowActionMode }), ...(filterFacets !== undefined && { filterFacets }), ...(filterValues !== undefined && { filterValues }), ...(onFilterChange !== undefined && { onFilterChange }), ...(onFilterReset !== undefined && { onFilterReset }), ...(dateRangeFacets !== undefined && { dateRangeFacets }), ...(onDateRangeChange !== undefined && { onDateRangeChange }), ...(chromeless !== undefined && { chromeless }), ...(scrollBody !== undefined && { scrollBody }), ...(screenPadding !== undefined && { screenPadding }), ...(expandedRowIds !== undefined && { expandedRowIds }), ...(onToggleRowExpanded !== undefined && { onToggleRowExpanded }), ...(renderExpandedRow !== undefined && { renderExpandedRow }), testId: "render-list-table" })] }));
+    return (_jsxs(_Fragment, { children: [createInPageHeader && PageHeader !== undefined && _jsx(PageHeader, { actions: createButton }), promotedActionButton !== undefined && PageHeader !== undefined && (_jsx(PageHeader, { actions: promotedActionButton })), referenceColumns.map((rc) => (_jsx(ReferenceLookupBridge, { field: rc.field, refEntity: rc.refEntity, labelField: rc.labelField, featureName: rc.refFeature, onMap: handleLookupMap }, rc.field))), _jsx(DataTable, { columns: enrichedVm.columns, rows: enrichedVm.rows, toolbarTitle: toolbarTitle, ...(onRowClick !== undefined && { onRowClick }), ...(composedEmptyState !== undefined && { emptyState: composedEmptyState }), ...(toolbarStart !== undefined && { toolbarStart }), ...(description !== undefined && !searchable && { toolbarDescription: description }), ...(toolbarEnd !== undefined && { toolbarEnd }), ...(sort !== undefined && { sort }), ...(onSortChange !== undefined && { onSortChange }), ...(pager !== undefined && { pager }), ...(onReachEnd !== undefined && { onReachEnd }), ...(loadingMore !== undefined && { loadingMore }), ...(hasMore !== undefined && { hasMore }), ...(itemNoun !== undefined && { itemNoun }), ...(rowActions !== undefined && { rowActions }), ...(rowActionMode !== undefined && { rowActionMode }), ...(rowGrouping !== undefined && { rowGrouping }), ...(rowTone !== undefined && { rowTone }), ...(filterFacets !== undefined && { filterFacets }), ...(filterValues !== undefined && { filterValues }), ...(onFilterChange !== undefined && { onFilterChange }), ...(onFilterReset !== undefined && { onFilterReset }), ...(dateRangeFacets !== undefined && { dateRangeFacets }), ...(onDateRangeChange !== undefined && { onDateRangeChange }), ...(chromeless !== undefined && { chromeless }), ...(scrollBody !== undefined && { scrollBody }), ...(screenPadding !== undefined && { screenPadding }), ...(expandedRowIds !== undefined && { expandedRowIds }), ...(onToggleRowExpanded !== undefined && { onToggleRowExpanded }), ...(renderExpandedRow !== undefined && { renderExpandedRow }), testId: "render-list-table" })] }));
 }
 // Header-Slot in der Listen-Toolbar (toolbarEnd): `screen.slots.header` ist
 // eine PlatformComponent (`{ react: { __component: "X" } }`), aufgelöst über

package/dist/hooks/use-list-url-state.d.ts

@@ -1,4 +1,5 @@
 import type { DataTableSort, DataTableSortDir } from "../primitives.js";
+export declare const NO_FILTER_URL_VALUE = "~";
 export type ListSortDir = DataTableSortDir;
 export type ListSort = DataTableSort;
 export type ListUrlState = {
@@ -40,4 +41,4 @@ export type ListUrlStateApi = ListUrlState & {
     }) => void;
 };
 export declare const PAGE_SIZE_OPTIONS: readonly number[];
-export declare function useListUrlState(screenId: string): ListUrlStateApi;
+export declare function useListUrlState(screenId: string, defaultFilters?: Readonly<Record<string, readonly string[]>>): ListUrlStateApi;

package/dist/hooks/use-list-url-state.js

@@ -8,12 +8,18 @@
 //   <screenId>.dir      — "asc" | "desc"
 //   <screenId>.q        — search term (URL-encoded)
 //   <screenId>.page     — 1-based page number (nur bei pagination="pages")
-//   <screenId>.f.<field> — Faceted-Filter: comma-joined selected values
+//   <screenId>.f.<field> — Faceted-Filter: comma-joined selected values;
+//                          NO_FILTER_URL_VALUE = "no filter", chosen on purpose
+//                          for a field that has a declared default
 //
 // Schreibt mit setSearchParams (replaceState — kein push), damit
 // Sort/Filter-Toggles nicht die Browser-History fluten.
 import { useCallback, useMemo } from "react";
 import { useNav } from "../app/nav.js";
+// A facet with a `defaultFilters` entry falls back to that default whenever
+// its URL key is absent. Clearing it therefore has to leave a marker, or the
+// default would come straight back.
+export const NO_FILTER_URL_VALUE = "~";
 // `.` als Trenner: lesbar (`?orders.sort=name`), kollidiert nicht mit
 // üblichen Field-Namen (kebab- oder camelCase ohne Punkt). Boot-Validator
 // pinnt screen.id ohne Punkt — siehe boot-validator entityList Section.
@@ -36,7 +42,7 @@ function parsePage(value) {
     const n = Number.parseInt(value, 10);
     return Number.isFinite(n) && n > 0 ? n : 1;
 }
-export function useListUrlState(screenId) {
+export function useListUrlState(screenId, defaultFilters) {
     const nav = useNav();
     const params = nav.searchParams;
     const sort = useMemo(() => {
@@ -60,10 +66,17 @@ export function useListUrlState(screenId) {
                 continue;
             // ponytail: comma-join — Facet-Werte sind select-Options/booleans
             // ohne Komma; upgrade auf repeated-keys falls je Komma-Werte nötig.
-            out[field] = v.split(",").filter((s) => s !== "");
+            out[field] = v === NO_FILTER_URL_VALUE ? [] : v.split(",").filter((s) => s !== "");
+        }
+        for (const [field, values] of Object.entries(defaultFilters ?? {})) {
+            if (!Object.hasOwn(out, field))
+                out[field] = values;
         }
         return out;
-    }, [params, filterPrefix]);
+    }, [params, filterPrefix, defaultFilters]);
+    const clearedFilterValue = useCallback((field) => defaultFilters !== undefined && Object.hasOwn(defaultFilters, field)
+        ? NO_FILTER_URL_VALUE
+        : null, [defaultFilters]);
     const setSort = useCallback((next) => {
         // Atomares Update: bei jedem Sort-Wechsel resetten wir auch die
         // Page (sonst wäre der User auf "Seite 5 von alter Sortierung"
@@ -97,10 +110,10 @@ export function useListUrlState(screenId) {
     }, [nav, screenId]);
     const setFilter = useCallback((field, values) => {
         nav.setSearchParams({
-            [key(screenId, `f.${field}`)]: values.length === 0 ? null : values.join(","),
+            [key(screenId, `f.${field}`)]: values.length === 0 ? clearedFilterValue(field) : values.join(","),
             [key(screenId, "page")]: null,
         });
-    }, [nav, screenId]);
+    }, [nav, screenId, clearedFilterValue]);
     const setDateRange = useCallback((field, next) => {
         nav.setSearchParams({
             [key(screenId, `f.${field}.from`)]: next.from === "" ? null : next.from,
@@ -110,10 +123,11 @@ export function useListUrlState(screenId) {
     }, [nav, screenId]);
     const clearFilters = useCallback(() => {
         const updates = { [key(screenId, "page")]: null };
-        for (const field of Object.keys(filters))
-            updates[key(screenId, `f.${field}`)] = null;
+        for (const field of Object.keys(filters)) {
+            updates[key(screenId, `f.${field}`)] = clearedFilterValue(field);
+        }
         nav.setSearchParams(updates);
-    }, [nav, screenId, filters]);
+    }, [nav, screenId, filters, clearedFilterValue]);
     return {
         sort,
         q,

package/dist/i18n-defaults.js

@@ -23,6 +23,7 @@ export const kumikoDefaultTranslations = {
         "kumiko.actions.back": "Back",
         "kumiko.actions.finish": "Finish",
         "kumiko.wizard.step": "Step {current} of {total}",
+        "kumiko.wizard.up-next": "Up next",
         "kumiko.wizard.step-with-title": "Step {current} of {total} · {title}",
         "kumiko.version.update-available": "A new version is available.",
         "kumiko.toast.learn-more": "Learn more",

package/dist/index.d.ts

@@ -67,7 +67,7 @@ export { createStaticLocaleResolver, FormalityProvider, LocaleProvider, mergeTra
 export { kumikoDefaultTranslations } from "./i18n-defaults.js";
 export { InsideDrawerProvider, useInsideDrawer } from "./inside-drawer.js";
 export { PageHeaderCompactProvider, PageHeaderSlotAvailableProvider, usePageHeaderCompact, usePageHeaderSlotAvailable, } from "./page-header-slot.js";
-export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableDateRangeFacet, DataTableFacet, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, FieldCellWidth, FieldProps, FillContainerProps, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputProps, JsonViewProps, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, WizardStepGroupProps, } from "./primitives.js";
+export type { ActionMenuItemSpec, ActionOverflowMenuProps, AppPrimitives, BannerProps, ButtonProps, CardOptions, CardProps, CardSlots, CopyButtonProps, CorePrimitives, DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, DataTableProps, DataTableRowAction, DataTableRowActionMode, DataTableRowGrouping, DataTableSort, DataTableSortDir, DialogProps, DrawerProps, EmbeddedListCellType, EmbeddedListColumn, EmbeddedListInputProps, EmbeddedListTotal, FieldCellWidth, FieldProps, FillContainerProps, FormProps, FormSectionNavItem, FormWidth, GridCellProps, GridProps, HeadingProps, InputProps, JsonViewProps, LightboxProps, LinkProps, MetricBandProps, MetricProps, ModalProps, PageHeaderProps, PrimitivesProviderProps, PrimitivesRegistry, ProgressProps, ProgressTone, PromoPanelAction, PromoPanelProps, RuntimeRenderer, SecretRevealProps, SecretRevealValue, SectionProps, ShareButtonProps, StatusBadgeProps, StatusTone, StepBarProps, StickyActionBarProps, StickyPrimaryActionMarker, TabsProps, TextProps, WizardStepGroupProps, } from "./primitives.js";
 export { PrimitivesProvider, STICKY_PRIMARY_ACTION_PROP, shouldRenderActionsIconOnly, statusToneForOptionTone, statusToneForValue, usePrimitives, } from "./primitives.js";
 export { buildWhatsAppShareUrl } from "./share-links.js";
 export { sortByAccessor } from "./sort-by-accessor.js";

package/dist/primitives.d.ts

@@ -1,5 +1,5 @@
 import type { ConfigCascade, ConfigScope, ConfigValueSource } from "@cosmicdrift/kumiko-framework/engine";
-import type { FieldIconKey, FormWidth, IconKey, NavIconKey, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { FieldIconKey, FormWidth, IconKey, NavIconKey, RowActionDisplay, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { FieldIssue, ListColumnViewModel, ListRowViewModel, RuntimeRenderer } from "@cosmicdrift/kumiko-headless";
 import { type ComponentType, type FormEvent, type KeyboardEvent, type ReactNode, type Ref } from "react";
 export type { RuntimeRenderer };
@@ -494,6 +494,10 @@ export type DataTableRowAction = {
      *  drives both the icon-left-of-text render and the icon-only collapse
      *  rule (see `shouldRenderActionsIconOnly`). */
     readonly icon?: IconKey;
+    /** Author-chosen inline form (`RowAction.display`). Set: the action stays
+     *  inline even in the adaptive layout and is exempt from the automatic
+     *  icon-only collapse. */
+    readonly display?: RowActionDisplay;
 };
 /** Teil-C action-icon collapse rule: a group of more than two actions where
  *  every member carries an icon renders icon-only instead of wall-to-wall
@@ -513,6 +517,22 @@ export type DataTableFacet = {
         readonly value: string;
         readonly label: string;
     }[];
+    /** Present: render the facet as a row of single-choice toggle chips instead
+     *  of a dropdown. A chip is pressed while the selection equals its values. */
+    readonly chips?: readonly DataTableFacetChip[];
+    /** Chips only: show each chip's `count` next to its label. */
+    readonly showCounts?: boolean;
+    /** Chips only: hide chips whose `count` is 0 (unless pressed). */
+    readonly hideEmpty?: boolean;
+};
+export type DataTableFacetChip = {
+    readonly id: string;
+    /** Translated chip label. */
+    readonly label: string;
+    /** Selection a click sets; `[]` clears the facet. */
+    readonly values: readonly string[];
+    /** Matching row count, undefined while unknown. */
+    readonly count?: number;
 };
 export type DataTableDateRangeFacet = {
     /** The facet's namespace (its date field) — a key, not a filter value. */
@@ -522,9 +542,19 @@ export type DataTableDateRangeFacet = {
     readonly from: string;
     readonly to: string;
 };
+/** Splits rows into collapsible groups (order of first appearance). A
+ *  renderer without grouping support shows the flat list. */
+export type DataTableRowGrouping = {
+    readonly keyOf: (row: ListRowViewModel) => string;
+    readonly headerLabel: (groupKey: string, rows: readonly ListRowViewModel[]) => string;
+    readonly startsCollapsed: (groupKey: string) => boolean;
+};
 export type DataTableProps = {
     readonly columns: readonly ListColumnViewModel[];
     readonly rows: readonly ListRowViewModel[];
+    readonly rowGrouping?: DataTableRowGrouping;
+    /** Tints a row. Renderers without row tinting ignore it. */
+    readonly rowTone?: (row: ListRowViewModel) => SelectOptionTone | undefined;
     readonly onRowClick?: (row: ListRowViewModel) => void;
     /** Aktuelle Sortierung (oder null = unsorted). Wenn columns ein
      *  `sortable: true`-Feld haben und onSortChange gesetzt ist, rendert
@@ -980,6 +1010,8 @@ export type DrawerProps = {
     readonly open: boolean;
     readonly onOpenChange: (open: boolean) => void;
     readonly title?: string;
+    /** Muted line under the title. */
+    readonly subtitle?: string;
     readonly children: ReactNode;
     readonly testId?: string;
 };
@@ -1098,6 +1130,14 @@ export type StepBarProps = {
     /** Vertical only: rail heading ("Step 4 of 6") and optional description. */
     readonly heading?: string;
     readonly description?: string;
+    /** Vertical only: line under each step label, same order as `steps`. */
+    readonly subtitles?: readonly (string | undefined)[];
+    /** Vertical only: box under the rail announcing the next step. */
+    readonly upNext?: {
+        readonly heading: string;
+        readonly title: string;
+        readonly subtitle?: string;
+    };
     readonly testId?: string;
     readonly compactTestId?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.332.0",
+  "version": "0.333.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,9 +15,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.332.0",
-    "@cosmicdrift/kumiko-headless": "0.332.0",
-    "@cosmicdrift/kumiko-types": "0.332.0",
+    "@cosmicdrift/kumiko-framework": "0.333.0",
+    "@cosmicdrift/kumiko-headless": "0.333.0",
+    "@cosmicdrift/kumiko-types": "0.333.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -28,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.332.0"
+    "@cosmicdrift/kumiko-locale-de": "0.333.0"
   },
   "repository": {
     "type": "git",

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.333.0",
+    "type": "improvement",
+    "title": "New optional screen options for facet chips, default filters, row action display, drawer titles, footer actions, grouped related lists and wizard side info",
+    "detail": "entityList: `facets` (per-field `display: \"chips\"`, `showCounts`, `hideEmpty`, `extraOptions`, or `false` to hide), `defaultFilters` (initial value only, the URL wins, \"no filter\" stays chosen) and `rowActionMode`. Row actions get `display: \"button\" | \"link\" | \"icon\"`; with `display` set an action stays inline next to the kebab. Drawer actions get `title` / `subtitle` (i18n keys, `{param}` filled from the row prefill). Edit fields get `submit: false` (kept out of the payload), actionForm gets `footerActions` (patch values, then submit), relatedList gets `groupBy` / `rowTone` / `rowActionMode`. Wizard sections get `subtitle`, `layout.wizard.aside.upNext` adds an \"up next\" box, entityEdit gets `titleTemplate`. `Button` gets a `pressed` style, the DataTable contract `rowGrouping` / `rowTone`, `StepBar` `subtitles` / `upNext`, `Drawer` `subtitle`.\n- Screenshot runner: `SCREENSHOT_DESKTOP_WIDTH` overrides the desktop viewport width (default 1920).",
+    "migration": "No code change needed."
+  },
   {
     "version": "0.332.0",
     "type": "improvement",