@cosmicdrift/kumiko-renderer 0.332.0 → 0.334.0

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, fieldAppendixPlacement, fieldDescription, fieldAccent, markChangedFields = false, entityId: entityIdProp, extensionInitialValues, onChange, onControlsReady, fields: fieldsFilter, disabled = false, hideActions, valueDisplay = "form", hideSectionTitles, fillScreenHeight, dirtyFooter, validateOnChange, 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 }),
         }
@@ -549,6 +569,11 @@ export function RenderEdit(props) {
     // keeps normal document-flow height untouched.
     const fillHeight = fillScreenHeight === true ||
         (hideSectionTitles === true && filteredSections[0]?.kind === "relatedList");
+    // A lone writeForm tab is the whole page, so its submit joins this form's
+    // footer (pinned to the window edge like every other screen's save)
+    // instead of sitting in the section's title row.
+    const isLoneWriteFormTab = hideSectionTitles === true && filteredSections[0]?.kind === "writeForm";
+    const [writeFormFooterAction, setWriteFormFooterAction] = useState(undefined);
     // Persistiert alle composed Extension-Sections mit der aufgelösten entityId.
     // false = eine Section schlug fehl (ihr i18n-Key landet im Banner). Ohne
     // Entity-Kontext (create-mode ohne route-id) gibt es nichts zu schreiben.
@@ -852,10 +877,7 @@ export function RenderEdit(props) {
     handleSubmitRef.current = handleSubmit;
     // Screen forms (entityEdit/actionForm filling the shell height) drop the card;
     // the title then lives in the shell header when the shell offers a slot.
-    const isScreenForm = fillScreenHeight === true &&
-        hideSectionTitles !== true &&
-        headerRegion === undefined &&
-        !insideDrawer;
+    const isScreenForm = fillScreenHeight === true && hideSectionTitles !== true && !insideDrawer;
     const titleInShell = PageHeader !== undefined &&
         pageHeaderSlotAvailable &&
         hideSectionTitles !== true &&
@@ -940,13 +962,41 @@ export function RenderEdit(props) {
     const hasFormActions = (isWizard && currentStep > 0) ||
         (isWizard && !isLastWizardStep) ||
         (showsSubmit && (!isWizard || isLastWizardStep)) ||
-        footerSlot !== undefined;
+        footerSlot !== undefined ||
+        writeFormFooterAction !== undefined;
     const nextStepTitle = isWizard ? filteredSections[currentStep + 1]?.title : undefined;
+    const isCreate = (() => {
+        const id = resolveExtensionEntityId(entityIdProp, vm.id);
+        return id == null || id === "";
+    })();
+    const changedFieldCount = Object.keys(snapshot.changes).length;
+    // Edit-mode screen forms always carry the dirty status (0 = quiet "No unsaved
+    // changes"); wizards keep the status-only-when-dirty behaviour.
+    const hasDirtyFooter = !isWizard &&
+        (dirtyFooter === true || (isScreenForm && !isCreate && headerRegion === undefined));
+    const unsavedCount = !hasDirtyFooter
+        ? undefined
+        : changedFieldCount > 0
+            ? changedFieldCount
+            : extensionDirty
+                ? 1
+                : 0;
+    const isSettingsList = screen.layout.variant === "settings-list" && hideSectionTitles !== true;
     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))), hasDirtyFooter && showsSubmit && unsavedCount !== undefined && unsavedCount > 0 && (_jsx(Button, { type: "button", variant: "ghost", disabled: isSubmitting || disabled, onClick: () => controller.reset(), testId: "render-edit-discard", [STICKY_PRIMARY_ACTION_PROP]: true, children: translate("kumiko.form.discard") })), 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")) }))] }));
+                    disabled, loading: isSubmitting, variant: submitVariant ?? "primary", testId: "render-edit-submit", children: translate(submitLabel ??
+                    (isWizard
+                        ? "kumiko.actions.finish"
+                        : hasDirtyFooter
+                            ? "kumiko.form.saveChanges"
+                            : "kumiko.actions.save")) })), writeFormFooterAction] }));
     // Title + Subtitle, create/edit-bewusst. i18n-Keys (mode = "create"|"edit"):
     //   screen:<id>.<mode>.title / .<mode>.subtitle
     // Fallback-Kette: mode-spezifisch → generisch (screen:<id>.title/.subtitle).
@@ -957,10 +1007,6 @@ export function RenderEdit(props) {
     // prose, same as it does for an unknown key (fw#2723 review). Same slot
     // section.description already fills for a section. Falls back to
     // undefined (no subtitle) when neither is set.
-    const isCreate = (() => {
-        const id = resolveExtensionEntityId(entityIdProp, vm.id);
-        return id == null || id === "";
-    })();
     const formMode = isCreate ? "create" : "edit";
     const recordTitle = !isCreate && screen.recordTitleField !== undefined
         ? resolveRecordTitle(initial[screen.recordTitleField])
@@ -976,24 +1022,22 @@ 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
         ? (resolveScreenText("subtitle") ??
             (screen.description !== undefined ? translate(screen.description) : undefined))
         : undefined;
+    // Embedded settings-list forms (dashboard panels) have no shell header: the
+    // form title/subtitle move into the first section's header column instead of
+    // floating as a heading above the band.
+    const titleInSettingsHeader = isSettingsList && !titleInShell;
     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 changedFieldCount = isCreate ? 0 : Object.keys(snapshot.changes).length;
-    const unsavedCount = isCreate || !isScreenForm
-        ? 0
-        : changedFieldCount > 0
-            ? changedFieldCount
-            : extensionDirty
-                ? 1
-                : 0;
+    const upNextSection = screen.layout.wizard?.aside?.upNext === true ? filteredSections[currentStep + 1] : undefined;
     const sectionNavItems = isScreenForm && !isStepped
         ? filteredSections.flatMap((section, index) => section.kind !== "extension" &&
             section.kind !== "relatedList" &&
@@ -1019,11 +1063,23 @@ export function RenderEdit(props) {
                     !pageHeaderCompact &&
                     ActionOverflowMenu !== undefined && {
                     actions: (_jsx(ActionOverflowMenu, { label: translate("kumiko.list.row-actions.more"), items: headerMenuItems, testId: "render-edit-header-menu" })),
-                }) })), _jsx(Form, { onSubmit: () => void handleSubmit(), ...(hideSectionTitles !== true && !titleInShell && { title: formTitle }), ...(formSubtitle !== undefined && !stepRail && { subtitle: formSubtitle }), ...(isScreenForm && { screenForm: true }), ...(unsavedCount > 0 && { unsavedCount }), ...(sectionNavItems.length > 0 && { sectionNav: sectionNavItems }), ...(stepRail && {
+                }) })), _jsx(Form, { onSubmit: () => void handleSubmit(), ...(hideSectionTitles !== true &&
+                    !titleInShell &&
+                    !titleInSettingsHeader && { title: formTitle }), ...(formSubtitle !== undefined &&
+                    !stepRail &&
+                    !titleInSettingsHeader && { subtitle: formSubtitle }), ...(isScreenForm && { screenForm: true }), ...(unsavedCount !== undefined &&
+                    (unsavedCount > 0 || hasDirtyFooter) && { unsavedCount }), ...(sectionNavItems.length > 0 && { sectionNav: sectionNavItems }), ...(stepRail && {
                     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))),
@@ -1119,19 +1175,29 @@ export function RenderEdit(props) {
                                 // Own submit button + dispatcher call, entirely independent of
                                 // this screen's (nonexistent, on projectionDetail) form submit —
                                 // rejected at boot in wizard layouts, so no WizardStepGroup here.
-                                return (_jsx(WriteFormSection, { section: section, featureName: featureName, translate: translate, hideTitle: hideSectionTitles, onSubmitted: () => onReload?.(), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }) }, section.title ?? `write-form-${sectionIndex}`));
+                                return (_jsx(WriteFormSection, { section: section, featureName: featureName, translate: translate, hideTitle: hideSectionTitles, onSubmitted: () => onReload?.(), ...(isLoneWriteFormTab && { onFooterAction: setWriteFormFooterAction }), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }) }, section.title ?? `write-form-${sectionIndex}`));
                             }
                             if (!section.visible)
                                 return null;
                             // Titellose Sections kollidieren sonst auf key/testId — Index-Fallback.
                             const sectionKey = section.title ?? `section-${sectionIndex}`;
-                            const renderFieldGrid = (fields, columns, gridKey) => (_jsx(Grid, { columns: columns, ...(usesFieldFlow && { flow: true }), children: fields.map((field) => (_jsx(GridCellForField, { field: disabled ? { ...field, readOnly: true } : field, columns: columns, ...(usesFieldFlow && { flow: true }), issues: snapshot.errors[field.field], onChange: (v) => {
+                            const renderFieldGrid = (fields, columns, gridKey) => (_jsx(Grid, { columns: columns, ...(isSettingsList ? { list: true } : usesFieldFlow && { flow: true }), children: fields.map((field) => (_jsx(GridCellForField, { field: disabled ? { ...field, readOnly: true } : field, columns: columns, ...(!isSettingsList && usesFieldFlow && { flow: true }), ...(isSettingsList && {
+                                        layout: "row",
+                                        accent: fieldAccent?.(field.field) === true,
+                                    }), issues: snapshot.errors[field.field], onChange: (v) => {
                                         controller.setField(field.field, v);
+                                        if (validateOnChange === true)
+                                            controller.validate([field.field]);
                                     }, GridCell: GridCell, featureName: featureName, ...(labelAppendix !== undefined && {
                                         labelAppendix: labelAppendix(field.field),
                                     }), ...(fieldAppendix !== undefined && {
                                         fieldAppendix: fieldAppendix(field.field),
-                                    }), allIssues: snapshot.errors, valueDisplay: valueDisplay, row: snapshot.values, ...(!isCreate && field.field in snapshot.changes && { changed: true }) }, field.field))) }, gridKey));
+                                    }), ...(fieldAppendixPlacement !== undefined && {
+                                        appendixPlacement: fieldAppendixPlacement,
+                                    }), ...(fieldDescription !== undefined && {
+                                        description: fieldDescription(field.field),
+                                    }), allIssues: snapshot.errors, valueDisplay: valueDisplay, row: snapshot.values, ...((!isCreate || markChangedFields) &&
+                                        field.field in snapshot.changes && { changed: true }) }, field.field))) }, gridKey));
                             // Tabs mode: the tab panel is the surface, so field sections render
                             // as unframed padded panels; group cards inside stay framed.
                             // Stays `Card`, not `Section` — Section always flattens to a
@@ -1162,10 +1228,16 @@ export function RenderEdit(props) {
                             // tab label right above it. Without a Tabs primitive the sections
                             // render stacked, and then the titles are what tells them apart.
                             const repeatsTabLabel = isTabs && isStepped;
-                            const sectionTitle = section.title === formTitle || repeatsTabLabel ? undefined : section.title;
+                            const headerFallback = titleInSettingsHeader && sectionIndex === 0;
+                            const sectionTitle = headerFallback
+                                ? (section.title ?? formTitle)
+                                : section.title === formTitle || repeatsTabLabel
+                                    ? undefined
+                                    : section.title;
+                            const sectionSubtitle = section.description ?? (headerFallback ? formSubtitle : undefined);
                             const sectionEl = (_jsxs(Section, { ...(sectionNavItems.some((item) => item.id === formSectionDomId(sectionIndex)) && {
                                     id: formSectionDomId(sectionIndex),
-                                }), ...(sectionTitle !== undefined && { title: sectionTitle }), ...(section.description !== undefined && { subtitle: section.description }), ...(section.icon !== undefined && { icon: section.icon }), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }), testId: `section-${sectionKey}`, children: [showsAllRequiredHint && insideDrawer && sectionIndex === 0 && allRequiredHint, renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`)] }, sectionKey));
+                                }), ...(sectionTitle !== undefined && { title: sectionTitle }), ...(sectionSubtitle !== undefined && { subtitle: sectionSubtitle }), ...(section.icon !== undefined && { icon: section.icon }), ...(sectionActionsEl !== undefined && { actions: sectionActionsEl }), ...(isSettingsList && { layout: "settings-list" }), testId: `section-${sectionKey}`, children: [showsAllRequiredHint && insideDrawer && sectionIndex === 0 && allRequiredHint, renderFieldGrid(section.fields, section.columns, `${sectionKey}-grid`)] }, sectionKey));
                             return wrapWizardStep(sectionKey, sectionEl);
                         }), formError !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-form-error", actions: formError.code === "version_conflict" && onReload !== undefined ? (_jsx(Button, { variant: "secondary", onClick: () => {
                                     onReload();

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

@@ -1,5 +1,6 @@
 import { type EditFieldViewModel, type FieldIssue } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode } from "react";
+import { type FieldProps } from "../primitives.js";
 export type RenderFieldProps = {
     readonly field: EditFieldViewModel;
     readonly issues?: readonly FieldIssue[];
@@ -14,6 +15,9 @@ export type RenderFieldProps = {
     /** Optionaler Zusatz-Inhalt der nach dem Input gerendert wird (z.B.
      *  ConfigCascade). */
     readonly fieldAppendix?: ReactNode;
+    readonly appendixPlacement?: FieldProps["appendixPlacement"];
+    readonly description?: ReactNode;
+    readonly status?: FieldProps["status"];
     /** Flat issues-by-path map (FormSnapshot.errors) — only relevant for
      *  type:"embedded" with embeddedListCells, to bucket row-/cell-issues
      *  (`${field}.${rowIndex}` / `${field}.${rowIndex}.${cellField}`).
@@ -33,6 +37,8 @@ export type RenderFieldProps = {
     readonly row?: Readonly<Record<string, unknown>>;
     /** Marks the field as modified against the loaded record (edit mode only). */
     readonly changed?: boolean;
+    readonly layout?: FieldProps["layout"];
+    readonly accent?: boolean;
 };
 export declare const AllFieldsRequiredProvider: import("react").Provider<boolean>;
-export declare function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, allIssues, valueDisplay, row, changed, }: RenderFieldProps): ReactNode;
+export declare function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, appendixPlacement, description, status, allIssues, valueDisplay, row, changed, layout, accent, }: RenderFieldProps): ReactNode;

package/dist/components/render-field.js

@@ -19,7 +19,7 @@ import { QueryOptionsSelect } from "./query-options-select.js";
 import { ReferenceCreateDialog } from "./reference-create-dialog.js";
 const AllFieldsRequiredContext = createContext(false);
 export const AllFieldsRequiredProvider = AllFieldsRequiredContext.Provider;
-export function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, allIssues, valueDisplay = "form", row, changed, }) {
+export function RenderField({ field, issues, onChange, featureName, labelAppendix, fieldAppendix, appendixPlacement, description, status, allIssues, valueDisplay = "form", row, changed, layout, accent, }) {
     const { Field, Input, Banner, Text, JsonView } = usePrimitives();
     // App-Locale (i18n) für money/date-Inputs — sonst fielen sie auf
     // navigator.language (Browser-Sprache) zurück statt der gewählten
@@ -42,7 +42,7 @@ export function RenderField({ field, issues, onChange, featureName, labelAppendi
     // 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.readOnly && field.renderer !== undefined ? (_jsx(FieldRendererOutput, { field: field, renderer: field.renderer, appLocale: appLocale, ...(row !== undefined && { row }) })) : field.type === "embedded" && field.embeddedListCells !== undefined ? (_jsx(EmbeddedListField, { field: field, id: id, onChange: onChange, allIssues: allIssues ?? {}, featureName: featureName ?? "" })) : field.type === "reference" ? (readOnlyText ? (_jsx(ReadOnlyReferenceValue, { field: field, featureName: featureName ?? "" })) : (_jsx(ReferenceInput, { field: field, id: id, hasError: hasError, onChange: onChange, Input: Input, featureName: featureName ?? "" }))) : field.type === "select" && field.selectOptionsQuery !== undefined && !readOnlyText ? (_jsx(QueryOptionsSelect, { field: field, query: field.selectOptionsQuery.query, payload: field.selectOptionsQuery.payload, id: id, hasError: hasError, onChange: onChange })) : readOnlyText && !isComplexFieldType(field.type) ? (_jsx(Text, { testId: `field-value-${field.field}`, children: readOnlyDisplayText(field, appLocale) })) : (renderInput({
+    const control = field.readOnly && field.renderer !== undefined ? (_jsx(FieldRendererOutput, { field: field, renderer: field.renderer, appLocale: appLocale, ...(row !== undefined && { row }) })) : field.type === "embedded" && field.embeddedListCells !== undefined ? (_jsx(EmbeddedListField, { field: field, id: id, onChange: onChange, allIssues: allIssues ?? {}, featureName: featureName ?? "" })) : field.type === "reference" ? (readOnlyText ? (_jsx(ReadOnlyReferenceValue, { field: field, featureName: featureName ?? "" })) : (_jsx(ReferenceInput, { field: field, id: id, hasError: hasError, onChange: onChange, Input: Input, featureName: featureName ?? "" }))) : field.type === "select" && field.selectOptionsQuery !== undefined && !readOnlyText ? (_jsx(QueryOptionsSelect, { field: field, query: field.selectOptionsQuery.query, payload: field.selectOptionsQuery.payload, row: row ?? { [field.field]: field.value }, id: id, hasError: hasError, onChange: onChange })) : readOnlyText && !isComplexFieldType(field.type) ? (_jsx(Text, { testId: `field-value-${field.field}`, children: readOnlyDisplayText(field, appLocale, t) })) : field.type === "text" && field.writeOnly === true && !readOnlyText ? (_jsx(WriteOnlyTextInput, { field: field, id: id, hasError: hasError, onChange: onChange, changed: changed === true })) : (renderInput({
         field,
         id,
         hasError,
@@ -55,7 +55,33 @@ export function RenderField({ field, issues, onChange, featureName, labelAppendi
         t,
         row,
     }));
-    return (_jsx(Field, { id: id, label: field.label, required: field.required && field.type !== "boolean" && !allFieldsRequired, ...(issues !== undefined && { issues }), ...(labelAppendix !== undefined && { labelAppendix }), ...(fieldAppendix !== undefined && { fieldAppendix }), ...(changed === true && { changed }), testId: `field-${field.field}`, children: control }));
+    return (_jsx(Field, { id: id, label: field.label, required: field.required && field.type !== "boolean" && !allFieldsRequired, ...(issues !== undefined && { issues }), ...(labelAppendix !== undefined && { labelAppendix }), ...(fieldAppendix !== undefined && { fieldAppendix }), ...(appendixPlacement !== undefined && { appendixPlacement }), ...(description !== undefined && { description }), ...(status !== undefined && { status }), ...(changed === true && { changed }), ...(layout !== undefined && { layout }), ...(accent === true && { accent }), testId: `field-${field.field}`, children: control }));
+}
+// Wire value of a writeOnly field is `true` (set) / `null` (empty), never the
+// secret. Typing sets a new value; an untouched or emptied input submits
+// nothing / "" which the server reads as "keep". `null` after a loaded `true`
+// (changed) means "remove on save".
+function WriteOnlyTextInput({ field, id, hasError, onChange, changed, }) {
+    const { Input } = usePrimitives();
+    const t = useTranslation();
+    const isSet = field.value === true;
+    const isMarkedForRemoval = field.value === null && changed;
+    if (isMarkedForRemoval) {
+        return (_jsx(Input, { kind: "password", id: id, name: field.field, disabled: true, hasError: hasError, value: "", onChange: () => { }, autoComplete: "new-password", placeholder: t("kumiko.field.writeOnly.willRemove"), testId: `field-write-only-removal-${field.field}`, trailingAction: {
+                icon: "undo",
+                label: t("kumiko.field.writeOnly.undo"),
+                onPress: () => onChange(true),
+            } }));
+    }
+    return (_jsx(Input, { kind: "password", id: id, name: field.field, disabled: field.readOnly, required: field.required && !isSet, hasError: hasError, value: typeof field.value === "string" ? field.value : "", onChange: (v) => onChange(v), autoComplete: "new-password", ...(isSet && { placeholder: t("kumiko.field.writeOnly.setPlaceholder") }), ...(isSet &&
+            !field.required &&
+            !field.readOnly && {
+            trailingAction: {
+                icon: "clear",
+                label: t("kumiko.field.writeOnly.remove"),
+                onPress: () => onChange(null),
+            },
+        }) }));
 }
 // Where a reference field's option rows come from, and which of their keys
 // holds the display text — the entity's own list handler plus `refLabelField`
@@ -488,10 +514,12 @@ function locatedValue(v) {
 // 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, appLocale) {
+function readOnlyDisplayText(field, appLocale, t) {
     const { type, value } = field;
     if (value === undefined || value === null || value === "")
         return "—";
+    if (type === "text" && field.writeOnly === true)
+        return t("kumiko.field.writeOnly.set");
     if (type === "text" && field.format === "password")
         return "••••••••";
     switch (type) {

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/components/write-form-section.d.ts

@@ -13,5 +13,9 @@ export type WriteFormSectionProps = {
      *  rendered alongside (before) the section's own submit button in the
      *  title-row actions slot. */
     readonly actions?: ReactNode;
+    /** Set when this section is a whole tab: the submit button is handed to
+     *  the host form's footer (pinned like every other screen's save) instead
+     *  of the section's title row. Called with undefined on unmount. */
+    readonly onFooterAction?: (action: ReactNode | undefined) => void;
 };
-export declare function WriteFormSection({ section, featureName, translate, hideTitle, onSubmitted, actions, }: WriteFormSectionProps): ReactNode;
+export declare function WriteFormSection({ section, featureName, translate, hideTitle, onSubmitted, actions, onFooterAction, }: WriteFormSectionProps): ReactNode;

package/dist/components/write-form-section.js

@@ -1,12 +1,12 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { I18N_KEY_PARAM } from "@cosmicdrift/kumiko-headless";
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import * as z from "zod";
 import { REQUIRED_FIELD_I18N_KEY } from "../app/form-schema.js";
 import { dispatcherErrorText } from "../app/write-failed-error.js";
 import { useForm } from "../hooks/use-form.js";
 import { useTranslation } from "../i18n.js";
-import { usePrimitives } from "../primitives.js";
+import { STICKY_PRIMARY_ACTION_PROP, usePrimitives } from "../primitives.js";
 import { GridCellForField } from "./grid-cell-for-field.js";
 // Same "has a value" rule as buildFormSchema's isPresent (app/form-schema.ts)
 // — duplicated because that helper walks raw EditFieldSpec + EntityDefinition,
@@ -45,7 +45,7 @@ function buildWriteFormSchema(fields) {
 // would render a second, invalid nested <form> inside the host's own form
 // element — so this mounts its own independent useForm() controller and
 // submits via a plain button click instead of native form submission.
-export function WriteFormSection({ section, featureName, translate, hideTitle, onSubmitted, actions, }) {
+export function WriteFormSection({ section, featureName, translate, hideTitle, onSubmitted, actions, onFooterAction, }) {
     const { Section, Card, Grid, GridCell, Button, Banner } = usePrimitives();
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
@@ -85,8 +85,20 @@ export function WriteFormSection({ section, featureName, translate, hideTitle, o
     // type="button" (not "submit") is load-bearing: this section is deliberately
     // NOT a nested <form> (see the component doc above), so a "submit" type
     // would instead trigger the host RenderEdit's own form submit.
-    const submitButton = (_jsx(Button, { type: "button", variant: "primary", disabled: isSubmitting, loading: isSubmitting, onClick: () => void handleSubmit(), testId: "write-form-section-submit", children: section.submitLabel ?? effectiveTranslate("kumiko.actions.save") }));
-    const titleRowActions = actions !== undefined ? (_jsxs(_Fragment, { children: [actions, submitButton] })) : (submitButton);
+    // The footer copy of the button outlives this render, so it calls the
+    // latest handleSubmit through a ref instead of capturing a stale closure.
+    const handleSubmitRef = useRef(handleSubmit);
+    handleSubmitRef.current = handleSubmit;
+    const submitLabel = section.submitLabel ?? effectiveTranslate("kumiko.actions.save");
+    const submitButton = (_jsx(Button, { type: "button", variant: "primary", disabled: isSubmitting, loading: isSubmitting, onClick: () => void handleSubmitRef.current(), testId: "write-form-section-submit", [STICKY_PRIMARY_ACTION_PROP]: true, children: submitLabel }));
+    // biome-ignore lint/correctness/useExhaustiveDependencies: submitButton is rebuilt every render; isSubmitting and submitLabel are everything it shows.
+    useEffect(() => {
+        if (onFooterAction === undefined)
+            return;
+        onFooterAction(submitButton);
+        return () => onFooterAction(undefined);
+    }, [onFooterAction, isSubmitting, submitLabel]);
+    const titleRowActions = onFooterAction !== undefined ? (actions) : actions !== undefined ? (_jsxs(_Fragment, { children: [actions, submitButton] })) : (submitButton);
     // Section always flattens to a borderless divider when rendered inside
     // RenderEdit's own <Form> in tabs mode (hideTitle) — an unframed Card panel
     // stands in, like render-edit.tsx's tabs-mode fields/extension branches.

package/dist/context/embedded-screen-context.d.ts

@@ -0,0 +1,5 @@
+import { type ReactNode } from "react";
+export declare function EmbeddedScreenProvider({ children }: {
+    readonly children: ReactNode;
+}): ReactNode;
+export declare function useIsEmbeddedScreen(): boolean;

package/dist/context/embedded-screen-context.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+// A host that already frames and pads the embedded screen (dashboard panel
+// with `chromeless`) marks the subtree, so list screens drop their own
+// screen padding and card frame instead of stacking it on the host's.
+const EmbeddedScreenContext = createContext(false);
+export function EmbeddedScreenProvider({ children }) {
+    return _jsx(EmbeddedScreenContext, { value: true, children: children });
+}
+export function useIsEmbeddedScreen() {
+    return useContext(EmbeddedScreenContext);
+}

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,