@cosmicdrift/kumiko-renderer 0.333.0 → 0.335.0

package/dist/components/render-edit.js

@@ -1,6 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { evalFieldCondition, isFieldsEditSection, normalizeEditField, PROJECTION_DETAIL_ENTITY, } from "@cosmicdrift/kumiko-framework/ui-types";
-import { computeEditViewModel } from "@cosmicdrift/kumiko-headless";
+import { evalFieldCondition, isFieldsEditSection, normalizeEditField, PROJECTION_DETAIL_ENTITY, sectionFieldSpecs, } from "@cosmicdrift/kumiko-framework/ui-types";
+import { computeEditViewModel, relevantFieldIssues, zodErrorToFieldIssues, } from "@cosmicdrift/kumiko-headless";
 import { RenderEditActionButton } from "./render-edit-action-button.js";
 import { AllFieldsRequiredProvider } from "./render-field.js";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
@@ -77,7 +77,7 @@ function deriveFormFields(screen) {
         // relatedList carries no `fields` for the form-condition map either.
         if (!isFieldsEditSection(section))
             continue;
-        for (const spec of section.fields) {
+        for (const spec of sectionFieldSpecs(section)) {
             const normalized = normalizeEditField(spec);
             out[normalized.field] = {
                 ...(normalized.visible !== undefined && {
@@ -94,16 +94,67 @@ function deriveFormFields(screen) {
     }
     return out;
 }
+// Dry-run parse against `schema` — NOT controller.validate(), which writes
+// field errors into the snapshot. Issues are filtered exactly like the
+// controller's validate(): hidden fields never count, `scope` narrows.
+function dryRunFieldIssues(schema, snapshot, scope, includeRoot) {
+    const parsed = schema.safeParse(snapshot.values);
+    if (parsed.success)
+        return [];
+    const hiddenFields = new Set(Object.entries(snapshot.fields)
+        .filter(([, state]) => !state.visible)
+        .map(([fieldKey]) => fieldKey));
+    return relevantFieldIssues(zodErrorToFieldIssues(parsed.error), {
+        hiddenFields,
+        ...(scope !== undefined && { scope }),
+        includeRoot,
+    });
+}
+// Index-independent: indices shift when a fields section hides.
+function wizardStepKey(section, index) {
+    const declaredId = section.kind === "fields" || section.kind === "extension" ? section.id : undefined;
+    return declaredId ?? section.title ?? `step-${index}`;
+}
+function isMoneyValue(value) {
+    return typeof value === "object" && value !== null && "amount" in value;
+}
+// The seeds buildInitialValues writes for NULL columns of an existing record.
+function isEmptyFormValue(value) {
+    if (value === null || value === undefined || value === "" || value === 0 || value === false) {
+        return true;
+    }
+    if (Array.isArray(value))
+        return value.length === 0;
+    return isMoneyValue(value) && value.amount === 0;
+}
+// select/boolean are excluded from the "holds user data" check: they are
+// often pre-filled (defaults, server-set values), so they say nothing about
+// whether the step was filled in. They still count through the validation.
+function isFieldsStepFilled(section, schema, snapshot) {
+    const fieldNames = section.fields.map((f) => f.field);
+    if (schema !== undefined && dryRunFieldIssues(schema, snapshot, fieldNames, false).length > 0) {
+        return false;
+    }
+    return section.fields.some((f) => f.visible &&
+        !f.readOnly &&
+        f.type !== "boolean" &&
+        f.type !== "select" &&
+        !isEmptyFormValue(f.value));
+}
 // Resolves an extension-section's `{ react: { __component: "X" } }` marker
 // to a registered React component via ExtensionSectionsProvider (filled in
 // createKumikoApp from clientFeatures.extensionSectionComponents) and
 // mounts it with the host entity name + id. Hook lives in its own
 // component so we don't call `use*` inside vm.sections.map (rules-of-
 // hooks would punish reordering sections between renders).
-function ExtensionSectionMount({ section, entityName: hostEntityName, entityId, initialValues, values, patch, validate, hideTitle, actions, }) {
+function ExtensionSectionMount({ section, entityName: hostEntityName, entityId, initialValues, values, patch, validate, hideTitle, actions, stepKey, onReportStepComplete, }) {
     const { Banner, FillContainer, Section, Text } = usePrimitives();
     const name = extensionSectionName(section.component);
     const Component = useExtensionSectionComponent(name);
+    const reportStepComplete = useCallback((complete) => {
+        if (stepKey !== undefined)
+            onReportStepComplete?.(stepKey, complete);
+    }, [stepKey, onReportStepComplete]);
     const testId = `section-extension-${section.title}`;
     if (Component === undefined) {
         const placeholder = (_jsx(Banner, { variant: "info", testId: `section-extension-placeholder-${section.title}`, children: _jsxs(Text, { children: ["Extension section component ", _jsx(Text, { variant: "code", children: name ?? "(no __component name)" }), " ", "not registered in clientFeatures.extensionSectionComponents."] }) }));
@@ -115,7 +166,7 @@ function ExtensionSectionMount({ section, entityName: hostEntityName, entityId,
         // uses for its own hideTitle branch).
         return hideTitle === true ? (FillContainer !== undefined ? (_jsx(FillContainer, { testId: testId, children: placeholder })) : (placeholder)) : (_jsx(Section, { title: section.title, testId: testId, children: placeholder }, section.title));
     }
-    const mounted = (_jsx(Component, { entityName: section.entityName ?? hostEntityName, entityId: entityId, initialValues: initialValues, values: values, patch: patch, validate: validate }));
+    const mounted = (_jsx(Component, { entityName: section.entityName ?? hostEntityName, entityId: entityId, initialValues: initialValues, values: values, patch: patch, validate: validate, ...(onReportStepComplete !== undefined && { reportStepComplete }) }));
     // Same reasoning as the placeholder branch above: tabs mode's outer Card
     // is the only frame this content gets, no nested Section divider.
     return hideTitle === true ? (FillContainer !== undefined ? (_jsx(FillContainer, { testId: testId, children: mounted })) : (mounted)) : (_jsx(Section, { ...(actions !== undefined && { actions }), title: section.title, testId: testId, children: mounted }));
@@ -162,7 +213,8 @@ function resolveTitleTemplate(template, values, translate, 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, footerActions, 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, leadContent, } = props;
+    const i18nScreenId = props.i18nScreenId ?? screen.id;
     const { customSubmit } = props;
     // Translate-Fallback: wenn der Caller keine Translate-Fn übergibt,
     // konsumieren wir den i18next-Context direkt. Sonst wären Field-
@@ -185,6 +237,9 @@ export function RenderEdit(props) {
     const [linkCopied, setLinkCopied] = useState(false);
     const [isSubmitting, setIsSubmitting] = useState(false);
     const [formError, setFormError] = useState(null);
+    // A rejected delete can carry several blocking reasons; the first one is the
+    // banner's headline (formError), the rest are listed beneath it.
+    const [extraDeleteIssues, setExtraDeleteIssues] = useState([]);
     // One state for all header actions (actions?), not per-button — only one
     // action can be in flight at a time, and this keeps the error surfaced in
     // the shared formError-adjacent banner region instead of inside the
@@ -192,6 +247,14 @@ export function RenderEdit(props) {
     // flex justify-end action bar).
     const [actionError, setActionError] = useState(null);
     const [rawStep, setRawStep] = useState(0);
+    const [passedStepKeys, setPassedStepKeys] = useState(() => new Set());
+    const [extensionStepComplete, setExtensionStepComplete] = useState({});
+    const reportExtensionStepComplete = useCallback((stepKey, complete) => {
+        setExtensionStepComplete((prev) => (prev[stepKey] === true) === complete ? prev : { ...prev, [stepKey]: complete });
+    }, []);
+    // Tabs have stable ids, so the active tab follows its id: a field change
+    // that hides an earlier tab must not shift the index onto another tab.
+    const [activeTabId, setActiveTabId] = useState(undefined);
     // Create-mode draftId (issue #1913) — resumed from `sessionStorage` (web)
     // on mount so a same-tab reload finds the right one of several parallel
     // create-sessions on this screen; `null` until the first step change
@@ -400,9 +463,12 @@ export function RenderEdit(props) {
         // on every keystroke, painting error messages while the user is still
         // typing. `valid` can therefore legitimately diverge from what's
         // currently rendered under the fields (the last *mutating* validate()
-        // call, e.g. from controls.validate() or submit()).
+        // call, e.g. from controls.validate() or submit()). The issues are
+        // filtered exactly like submit()'s validate: hidden fields and fields
+        // outside the `fields` scope never make the form invalid.
         const currentSchema = schemaRef.current;
-        const valid = currentSchema === undefined ? true : currentSchema.safeParse(snapshot.values).success;
+        const valid = currentSchema === undefined ||
+            dryRunFieldIssues(currentSchema, snapshot, scopeFieldNamesRef.current, true).length === 0;
         cb({
             values: snapshot.values,
             changes: snapshot.changes,
@@ -569,6 +635,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.
@@ -588,12 +659,45 @@ export function RenderEdit(props) {
     // Clamped on read, not on write: section visibility is value-dependent, so a
     // stored stepIndex can point past what is currently rendered — that lands on
     // the last step instead of an empty one.
-    const currentStep = Math.min(rawStep, lastStepIndex);
+    const activeTabIndex = isTabs && activeTabId !== undefined
+        ? filteredSections.findIndex((s, i) => tabIdAt(s, i) === activeTabId)
+        : -1;
+    const currentStep = activeTabIndex !== -1 ? activeTabIndex : Math.min(rawStep, lastStepIndex);
     // Kept fresh for patchAndScheduleDraftSave's debounce timer above, which
     // is defined before `currentStep` exists (it depends on `filteredSections`,
     // computed further up from `vm`) and so cannot close over it directly.
     currentStepRef.current = currentStep;
     const isLastWizardStep = currentStep >= lastStepIndex;
+    const wizardDoneSteps = useMemo(() => {
+        if (!isWizard || isCreateMode)
+            return undefined;
+        const snapshotForDryRun = { values: snapshot.values, fields: snapshot.fields };
+        return filteredSections.map((section, index) => {
+            if (passedStepKeys.has(wizardStepKey(section, index)))
+                return true;
+            if (section.kind === "fields")
+                return isFieldsStepFilled(section, schema, snapshotForDryRun);
+            return (section.kind === "extension" &&
+                extensionStepComplete[wizardStepKey(section, index)] === true);
+        });
+    }, [
+        isWizard,
+        isCreateMode,
+        filteredSections,
+        passedStepKeys,
+        extensionStepComplete,
+        schema,
+        snapshot.values,
+        snapshot.fields,
+    ]);
+    const updateModeStepBarProps = wizardDoneSteps === undefined
+        ? {}
+        : { doneSteps: wizardDoneSteps, selectableSteps: "all" };
+    function jumpToStep(index) {
+        setRawStep(index);
+        if (isTabs)
+            setActiveTabId(tabIdAt(filteredSections[index], index));
+    }
     // Step transitions only — never per keystroke. Deliberately not awaited: a
     // failed draft save must not block the step change.
     //
@@ -633,11 +737,13 @@ export function RenderEdit(props) {
             console.warn(`RenderEdit: draftKey "${key}" is ${key.length} chars, over the server's ${FORM_DRAFT_KEY_MAX_LENGTH}-char limit — skipping this draft save. Shorten screen.id or entity id.`);
             return;
         }
-        const passwordFieldNames = new Set(vm.sections.flatMap((section) => section.kind === "fields"
-            ? section.fields.filter((f) => f.format === "password").map((f) => f.field)
+        const secretFieldNames = new Set(vm.sections.flatMap((section) => section.kind === "fields"
+            ? section.fields
+                .filter((f) => f.format === "password" || f.writeOnly === true)
+                .map((f) => f.field)
             : []));
-        // A password field never enters the persisted draft blob — it would be stored in the clear and restored on resume.
-        const draftValues = Object.fromEntries(Object.entries(controller.getSnapshot().values).filter(([field]) => !passwordFieldNames.has(field)));
+        // A password or writeOnly field never enters the persisted draft blob — it would be stored in the clear and restored on resume.
+        const draftValues = Object.fromEntries(Object.entries(controller.getSnapshot().values).filter(([field]) => !secretFieldNames.has(field)));
         void dispatcher
             .write(FORM_DRAFT_SAVE, {
             draftKey: key,
@@ -665,29 +771,45 @@ export function RenderEdit(props) {
             setRawStep(next);
             return;
         }
-        const section = filteredSections[currentStep];
-        const fieldNames = section?.kind === "fields" ? section.fields.map((f) => f.field) : [];
         // skip: the current step has field errors — no transition, no draft save.
-        if (fieldNames.length > 0 && !controller.validate(fieldNames))
+        if (currentStepHasFieldErrors())
             return;
+        if (!isCreateMode) {
+            const leftSection = filteredSections[currentStep];
+            if (leftSection !== undefined) {
+                const leftKey = wizardStepKey(leftSection, currentStep);
+                setPassedStepKeys((prev) => (prev.has(leftKey) ? prev : new Set(prev).add(leftKey)));
+            }
+        }
         setRawStep(next);
         saveDraft(next);
     }
+    function currentStepHasFieldErrors() {
+        const section = filteredSections[currentStep];
+        const fieldNames = section?.kind === "fields" ? section.fields.map((f) => f.field) : [];
+        return fieldNames.length > 0 && !controller.validate(fieldNames);
+    }
     function handleWizardBack() {
-        handleWizardJumpBack(currentStep - 1);
+        handleWizardStepSelect(currentStep - 1);
     }
-    // Only backwards: a forward jump would skip the per-step validate() gate.
-    function handleWizardJumpBack(targetStep) {
-        if (targetStep >= currentStep)
+    // Update mode: the record already exists and the final Save validates the
+    // whole form and jumps to the first erroring step (findFirstErroringStep), so
+    // skipping steps forward is safe; leaving the current step still goes through
+    // its validate gate.
+    function handleWizardStepSelect(targetStep) {
+        if (targetStep === currentStep)
             return;
-        const previous = Math.max(targetStep, 0);
-        hasNavigatedRef.current = true;
-        if (disabled) {
-            setRawStep(previous);
+        const isForward = targetStep > currentStep;
+        // Create mode: a forward jump would skip the per-step validate() gate.
+        if (isForward && isCreateMode)
             return;
-        }
-        setRawStep(previous);
-        saveDraft(previous);
+        if (isForward && !disabled && currentStepHasFieldErrors())
+            return;
+        const clampedTarget = Math.min(Math.max(targetStep, 0), lastStepIndex);
+        hasNavigatedRef.current = true;
+        setRawStep(clampedTarget);
+        if (!disabled)
+            saveDraft(clampedTarget);
     }
     async function discardDraft() {
         // skip: this screen does not persist a draft.
@@ -818,6 +940,7 @@ export function RenderEdit(props) {
             let extensionsPersisted = true;
             if (result.isSuccess) {
                 setFormError(null);
+                setExtraDeleteIssues([]);
                 // `isNoOp: true` (payloadMode "changes", pre-filled form submitted
                 // untouched) means controller.submit() never called dispatcher.write
                 // — nothing to discard, and discarding here would delete a draft the
@@ -838,7 +961,7 @@ export function RenderEdit(props) {
                 if (isStepped) {
                     const step = findFirstErroringStep(Object.keys(controller.getSnapshot().errors));
                     if (step !== undefined)
-                        setRawStep(step);
+                        jumpToStep(step);
                 }
             }
             else {
@@ -854,8 +977,9 @@ export function RenderEdit(props) {
                 if (isStepped) {
                     const step = findFirstErroringStep(issuePaths);
                     if (step !== undefined)
-                        setRawStep(step);
+                        jumpToStep(step);
                 }
+                setExtraDeleteIssues([]);
                 setFormError(hasIssueWithoutRenderedField(issuePaths, filteredSections) ? result.error : null);
             }
             // skip: on entity-success-but-extension-failure the extension-error
@@ -872,10 +996,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 &&
@@ -953,25 +1074,53 @@ export function RenderEdit(props) {
     const isFieldlessSubmitForm = isFieldless && screen.entity !== PROJECTION_DETAIL_ENTITY;
     const showsSubmit = isFormEditable || hasExtensionRegistrations || isFieldlessSubmitForm;
     const footerSlot = screen.slots?.footer;
+    // An unregistered footer component renders null, so only a resolvable one may
+    // count as an action (else read-only screens get an empty footer strip).
+    const FooterSlotComponent = useExtensionSectionComponent(footerSlot !== undefined ? extensionSectionName(footerSlot) : undefined);
     // Mirrors every branch inside formActions below — without this guard
     // DefaultForm renders an empty footer strip (border + padding, no content)
     // on read-only detail screens, since `actions` would otherwise always be
     // a defined (if empty) fragment.
-    const hasFormActions = (isWizard && currentStep > 0) ||
-        (isWizard && !isLastWizardStep) ||
-        (showsSubmit && (!isWizard || isLastWizardStep)) ||
-        footerSlot !== undefined;
+    const showWizardBack = isWizard && currentStep > 0;
+    const showWizardNext = isWizard && !isLastWizardStep;
+    const showSubmit = showsSubmit && (!isWizard || isLastWizardStep);
+    const hasFormActions = showWizardBack ||
+        showWizardNext ||
+        showSubmit ||
+        FooterSlotComponent !== undefined ||
+        writeFormFooterAction !== undefined;
     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
+    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: [showWizardBack && (_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: hasUnsavedInput, 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") })), showWizardNext && (_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) &&
+                    : translate("kumiko.actions.next") })), showSubmit &&
                 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) ||
+                    }, 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") })), showSubmit && (_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).
@@ -982,18 +1131,14 @@ 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])
         : undefined;
     const resolveScreenText = (suffix) => {
         for (const key of [
-            `screen:${screen.id}.${formMode}.${suffix}`,
-            `screen:${screen.id}.${suffix}`,
+            `screen:${i18nScreenId}.${formMode}.${suffix}`,
+            `screen:${i18nScreenId}.${suffix}`,
         ]) {
             const value = translate(key);
             if (value !== key)
@@ -1001,26 +1146,26 @@ export function RenderEdit(props) {
         }
         return undefined;
     };
-    const plainFormTitle = resolveScreenText("title") ?? screen.id;
+    const plainFormTitle = resolveScreenText("title") ?? i18nScreenId;
     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.
+    // In tabs mode (hideSectionTitles) screen.description is dropped — the head
+    // card carries it — but an explicit subtitle i18n override has no other
+    // source there, so it stays unless it merely resolves to the description.
+    const explicitSubtitle = resolveScreenText("subtitle");
+    const descriptionSubtitle = screen.description !== undefined ? translate(screen.description) : undefined;
     const formSubtitle = hideSectionTitles !== true
-        ? (resolveScreenText("subtitle") ??
-            (screen.description !== undefined ? translate(screen.description) : undefined))
-        : undefined;
+        ? (explicitSubtitle ?? descriptionSubtitle)
+        : explicitSubtitle !== descriptionSubtitle
+            ? explicitSubtitle
+            : 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 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
-        : changedFieldCount > 0
-            ? changedFieldCount
-            : extensionDirty
-                ? 1
-                : 0;
     const sectionNavItems = isScreenForm && !isStepped
         ? filteredSections.flatMap((section, index) => section.kind !== "extension" &&
             section.kind !== "relatedList" &&
@@ -1046,8 +1191,13 @@ 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 && {
-                    sideRail: (_jsx(StepBar, { steps: filteredSections.map((section) => section.title ?? ""), currentIndex: currentStep, compactLabel: compactStepLabel, onStepSelect: handleWizardJumpBack, orientation: "vertical", heading: translate("kumiko.wizard.step", {
+                }) })), _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: handleWizardStepSelect, ...updateModeStepBarProps, orientation: "vertical", heading: translate("kumiko.wizard.step", {
                             current: currentStep + 1,
                             total: lastStepIndex + 1,
                         }), ...(formSubtitle !== undefined && { description: formSubtitle }), subtitles: filteredSections.map((section) => section.kind === "fields" ? section.subtitle : undefined), ...(upNextSection !== undefined && {
@@ -1059,12 +1209,12 @@ export function RenderEdit(props) {
                             },
                         }), 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: [
+                    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: [leadContent, 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))),
                                 _jsx(Button, { type: "button", variant: "link", onClick: () => setDraftCandidates(null), testId: "render-edit-draft-start-new", children: translate("kumiko.form.draft.start-new") }, "start-new"),
                             ], children: _jsx(Text, { children: translate(draftCandidates.length === 1
                                     ? "kumiko.form.draft.resume-single"
-                                    : "kumiko.form.draft.resume-multiple") }) })), isWizard && !stepRail && (_jsxs(_Fragment, { children: [Progress !== undefined && (_jsx(Progress, { value: (currentStep + 1) / (lastStepIndex + 1), testId: "render-edit-wizard-progress" })), StepBar === undefined ? (_jsx(Text, { variant: "small", testId: "render-edit-wizard-step-label", children: compactStepLabel })) : (_jsx(StepBar, { steps: filteredSections.map((section) => section.title ?? ""), currentIndex: currentStep, compactLabel: compactStepLabel, onStepSelect: handleWizardJumpBack, testId: "render-edit-wizard-steps", compactTestId: "render-edit-wizard-step-label" }))] })), isTabs &&
+                                    : "kumiko.form.draft.resume-multiple") }) })), isWizard && !stepRail && (_jsxs(_Fragment, { children: [Progress !== undefined && (_jsx(Progress, { value: (currentStep + 1) / (lastStepIndex + 1), testId: "render-edit-wizard-progress" })), StepBar === undefined ? (_jsx(Text, { variant: "small", testId: "render-edit-wizard-step-label", children: compactStepLabel })) : (_jsx(StepBar, { steps: filteredSections.map((section) => section.title ?? ""), currentIndex: currentStep, compactLabel: compactStepLabel, onStepSelect: handleWizardStepSelect, ...updateModeStepBarProps, testId: "render-edit-wizard-steps", compactTestId: "render-edit-wizard-step-label" }))] })), isTabs &&
                             (() => {
                                 // No Tabs primitive registered → every section renders stacked
                                 // (stepHidden below is gated on the same condition), which is the
@@ -1080,7 +1230,7 @@ export function RenderEdit(props) {
                                         // skip: the strip reported an id no section owns.
                                         if (index === -1)
                                             return;
-                                        setRawStep(index);
+                                        jumpToStep(index);
                                     } }));
                             })(), filteredSections.map((section, sectionIndex) => {
                             // turns this section's own `actions` (RowAction[]) into
@@ -1120,7 +1270,11 @@ export function RenderEdit(props) {
                                 const mount = (_jsx(ExtensionSectionMount, { section: section, entityName: vm.entityName, entityId: resolveExtensionEntityId(entityIdProp, vm.id), initialValues: extensionInitialValues, values: snapshot.values, 
                                     // @cast-boundary form-values: ExtensionSectionProps is not generic
                                     // over TValues; controller is mount-lifetime-stable, see onControlsReady above.
-                                    patch: patchAndScheduleDraftSave, validate: scopedValidate, hideTitle: hideSectionTitles, ...(hideSectionTitles !== true &&
+                                    patch: patchAndScheduleDraftSave, validate: scopedValidate, hideTitle: hideSectionTitles, ...(isWizard &&
+                                        !isCreateMode && {
+                                        stepKey: wizardStepKey(section, sectionIndex),
+                                        onReportStepComplete: reportExtensionStepComplete,
+                                    }), ...(hideSectionTitles !== true &&
                                         sectionActionsEl !== undefined && { actions: sectionActionsEl }) }, section.title));
                                 // Tabs mode: an unframed padded panel (the tab panel is the
                                 // surface), so extension content neither sits flush at the shell
@@ -1153,19 +1307,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
@@ -1196,20 +1360,28 @@ 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: () => {
+                        }), formError !== null && (_jsxs(Banner, { variant: "error", testId: "render-edit-form-error", actions: formError.code === "version_conflict" && onReload !== undefined ? (_jsx(Button, { variant: "secondary", onClick: () => {
                                     onReload();
                                     setFormError(null);
-                                }, testId: "render-edit-form-error-reload", children: translate("kumiko.actions.reload") })) : undefined, children: _jsx(Text, { testId: "render-edit-form-error-key", children: translate(formError.i18nKey, formError.i18nParams) }) })), extensionErrorKey !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-extension-error", children: _jsx(Text, { testId: "render-edit-extension-error-key", children: translate(extensionErrorKey) }) })), actionError !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-action-error", children: actionError })), onDelete !== undefined && (_jsx(Dialog, { open: confirmDeleteOpen, onOpenChange: setConfirmDeleteOpen, title: translate("kumiko.actions.delete-confirm"), confirmLabel: translate("kumiko.actions.delete"), variant: "danger", onConfirm: async () => {
+                                    setExtraDeleteIssues([]);
+                                }, testId: "render-edit-form-error-reload", children: translate("kumiko.actions.reload") })) : undefined, children: [_jsx(Text, { testId: "render-edit-form-error-key", children: translate(formError.i18nKey, formError.i18nParams) }), extraDeleteIssues.map((issue) => (_jsx(Text, { testId: "render-edit-form-error-extra", children: translate(issue.i18nKey, issue.params) }, `${issue.path}:${issue.i18nKey}`)))] })), (snapshot.errors["(root)"] ?? []).map((issue) => (_jsx(Banner, { variant: "error", testId: "render-edit-root-issue", children: _jsx(Text, { children: translate(issue.i18nKey, issue.params) }) }, issue.i18nKey))), extensionErrorKey !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-extension-error", children: _jsx(Text, { testId: "render-edit-extension-error-key", children: translate(extensionErrorKey) }) })), actionError !== null && (_jsx(Banner, { variant: "error", testId: "render-edit-action-error", children: actionError })), onDelete !== undefined && (_jsx(Dialog, { open: confirmDeleteOpen, onOpenChange: setConfirmDeleteOpen, title: translate("kumiko.actions.delete-confirm"), confirmLabel: translate("kumiko.actions.delete"), variant: "danger", onConfirm: async () => {
                                 const rejection = await onDelete();
                                 // A rejected delete (e.g. a preDelete hook) carries its reason in
                                 // the field issues; the top-level key is only "validation failed".
                                 if (rejection !== undefined) {
-                                    const issue = rejection.details?.fields?.[0];
+                                    const [issue, ...otherIssues] = rejection.details?.fields ?? [];
+                                    setExtraDeleteIssues(otherIssues);
                                     setFormError(issue === undefined
                                         ? rejection
                                         : { ...rejection, i18nKey: issue.i18nKey, i18nParams: issue.params });

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;