@cosmicdrift/kumiko-renderer 0.334.0 → 0.336.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";
@@ -14,7 +14,7 @@ import { useForm } from "../hooks/use-form.js";
 import { useTranslation } from "../i18n.js";
 import { useInsideDrawer } from "../inside-drawer.js";
 import { usePageHeaderCompact, usePageHeaderSlotAvailable } from "../page-header-slot.js";
-import { STICKY_PRIMARY_ACTION_PROP, shouldRenderActionsIconOnly, usePrimitives, } from "../primitives.js";
+import { FOOTER_ACTION_ROLE_PROP, NARROW_LABEL_PROP, STICKY_PRIMARY_ACTION_PROP, shouldRenderActionsIconOnly, usePrimitives, } from "../primitives.js";
 import { GridCellForField } from "./grid-cell-for-field.js";
 import { RelatedListSection } from "./related-list-section.js";
 import { filterEditSections, hasEditableSection, hasIssueWithoutRenderedField, resolveExtensionEntityId, shouldNotifyCaller, } from "./render-edit-logic.js";
@@ -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, 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 { 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,
@@ -593,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.
     //
@@ -638,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,
@@ -670,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.
@@ -823,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
@@ -843,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 {
@@ -859,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
@@ -955,14 +1074,20 @@ 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 isCreate = (() => {
@@ -982,14 +1107,14 @@ export function RenderEdit(props) {
                 ? 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
+    const formActions = (_jsxs(_Fragment, { children: [showWizardBack && (_jsx(Button, { type: "button", variant: "secondary", icon: "chevron-left", onClick: handleWizardBack, testId: "render-edit-wizard-back", [FOOTER_ACTION_ROLE_PROP]: "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", [FOOTER_ACTION_ROLE_PROP]: "primary",
+                [NARROW_LABEL_PROP]: translate("kumiko.actions.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))), 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) ||
+                    }, 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
@@ -1013,8 +1138,8 @@ export function RenderEdit(props) {
         : 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)
@@ -1022,14 +1147,18 @@ 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.
@@ -1069,7 +1198,7 @@ export function RenderEdit(props) {
                     !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", {
+                    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 && {
@@ -1081,12 +1210,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
@@ -1102,7 +1231,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
@@ -1142,7 +1271,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
@@ -1239,15 +1372,17 @@ export function RenderEdit(props) {
                                     id: formSectionDomId(sectionIndex),
                                 }), ...(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.js

@@ -10,7 +10,7 @@ import { screenAccessAllows } from "../app/screen-access.js";
 import { useUserRoles } from "../context/user-roles-context.js";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
 import { useQuery } from "../hooks/use-query.js";
-import { referenceLookupSource } from "../hooks/use-reference-lookup.js";
+import { referenceOptionSource } from "../hooks/use-reference-lookup.js";
 import { useLocale, useTranslation } from "../i18n.js";
 import { usePrimitives } from "../primitives.js";
 import { EmbeddedListField } from "./embedded-list-field.js";
@@ -83,16 +83,6 @@ function WriteOnlyTextInput({ field, id, hasError, onChange, changed, }) {
             },
         }) }));
 }
-// 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`
-// by default, or an author-supplied handler whose rows carry `label`
-// (fw#2780), for targets with no readable column of their own.
-function referenceOptionSource(field, refFeature, refEntity) {
-    if (field.refOptionsQuery !== undefined) {
-        return { queryQn: field.refOptionsQuery, labelKey: "label" };
-    }
-    return referenceLookupSource(refFeature, refEntity, field.refLabelField ?? "id");
-}
 // Tier 2.7e-3 + 2.1c: Reference-Input rendert eine Searchable Combobox
 // gefüllt aus einer Live-Query auf die referenced Entity. Default-
 // Limit: 200 — bei größeren Datasets fehlt der Tail im Dropdown
@@ -464,15 +454,22 @@ function resolveMoneyCurrency(value, fieldCurrency) {
     }
     return fieldCurrency ?? "EUR";
 }
+// The suffix span is absolutely positioned inside a fixed right padding sized
+// for short symbols; a free-text sibling value longer than any real unit
+// symbol would overflow the number.
+const MAX_SIBLING_UNIT_LENGTH = 8;
 // Static unit → used as-is. Sibling-field reference → read the live row
-// value; missing/empty/non-string sibling means no suffix, never a guess.
+// value; missing/empty/non-string/overlong sibling means no suffix, never a guess.
 function resolveNumberUnit(unit, row) {
     if (unit === undefined)
         return undefined;
     if (typeof unit === "string")
         return unit;
     const sibling = row?.[unit.field];
-    return typeof sibling === "string" && sibling.length > 0 ? sibling : undefined;
+    if (typeof sibling !== "string")
+        return undefined;
+    const trimmed = sibling.trim();
+    return trimmed.length > 0 && trimmed.length <= MAX_SIBLING_UNIT_LENGTH ? trimmed : undefined;
 }
 function moneyMinorValue(v, currency) {
     if (v === undefined || v === null || v === "")

package/dist/components/render-list.js

@@ -6,11 +6,11 @@ import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
 import { useTranslation } from "../i18n.js";
 import { usePageHeaderCompact, usePageHeaderSlotAvailable } from "../page-header-slot.js";
 import { shouldRenderActionsIconOnly, usePrimitives, } from "../primitives.js";
+import { needsActionConfirm } from "./render-edit-action-button.js";
 const SEARCH_DEBOUNCE_MS = 300;
-// Fire-and-forget actions (schema navigate/drawer) can leave the toolbar for the
-// page header without losing the confirm dialog or busy/error surfacing.
+// Icon-less actions are promoted too (with a "plus" fallback at the call site).
 function isHeaderPromotableToolbarAction(action) {
-    return (action.style === "primary" && action.confirm === undefined && action.confirmRequired === false);
+    return action.style === "primary" && !needsActionConfirm(action);
 }
 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, rowGrouping, rowTone, toolbarActions, filterFacets, filterValues, onFilterChange, onFilterReset, dateRangeFacets, onDateRangeChange, chromeless, scrollBody, screenPadding, expandedRowIds, onToggleRowExpanded, renderExpandedRow, } = props;
@@ -147,7 +147,7 @@ export function RenderList(props) {
         pageHeaderCompact
         ? toolbarActions?.find(isHeaderPromotableToolbarAction)
         : undefined;
-    const promotedActionButton = promotedToolbarAction !== undefined ? (_jsx(Button, { variant: "primary", icon: promotedToolbarAction.icon ?? "plus", size: "icon", ariaLabel: promotedToolbarAction.label, title: promotedToolbarAction.label, onClick: () => void promotedToolbarAction.onTrigger(), testId: `render-list-toolbar-action-${promotedToolbarAction.id}` })) : undefined;
+    const promotedActionButton = promotedToolbarAction !== undefined ? (_jsx(ToolbarActionView, { action: { ...promotedToolbarAction, icon: promotedToolbarAction.icon ?? "plus" }, iconOnly: true, Button: Button, Dialog: Dialog, Banner: Banner })) : undefined;
     const toolbarActionsInToolbar = toolbarActions?.filter((a) => a !== promotedToolbarAction) ?? [];
     const hasToolbarActionsInToolbar = toolbarActionsInToolbar.length > 0;
     const toolbarEnd = hasHeaderSlot ||
@@ -239,9 +239,9 @@ function ToolbarActionView({ action, iconOnly = false, Button, Dialog, Banner, }
         }
     };
     const variant = action.style ?? "secondary";
-    const needsConfirm = action.confirm !== undefined || (action.confirmRequired ?? action.style === "danger");
+    const needsConfirm = needsActionConfirm(action);
     const showIconOnly = iconOnly && action.icon !== undefined;
-    return (_jsxs(_Fragment, { children: [_jsx(Button, { variant: variant, loading: busy, ...(action.icon !== undefined && { icon: action.icon }), size: showIconOnly ? "icon" : "sm", ...(showIconOnly && { ariaLabel: action.label }), onClick: () => {
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { variant: variant, loading: busy, ...(action.icon !== undefined && { icon: action.icon }), size: showIconOnly ? "icon" : "sm", ...(showIconOnly && { ariaLabel: action.label, title: action.label }), onClick: () => {
                     if (needsConfirm) {
                         setConfirmOpen(true);
                     }

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

@@ -2,24 +2,13 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { I18N_KEY_PARAM } from "@cosmicdrift/kumiko-headless";
 import { useEffect, useMemo, useRef, useState } from "react";
 import * as z from "zod";
-import { REQUIRED_FIELD_I18N_KEY } from "../app/form-schema.js";
+import { isPresent, 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 { 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,
-// unavailable here: this section only ever sees computeEditViewModel's
-// already-resolved EditFieldViewModel[] (required/readOnly/visible are plain
-// booleans by the time render-edit.tsx hands the section to this component).
-function isPresent(value) {
-    if (value === undefined || value === null || value === "")
-        return false;
-    if (Array.isArray(value) && value.length === 0)
-        return false;
-    return true;
-}
+import { hasIssueWithoutVisibleField } from "./render-edit-logic.js";
 function buildWriteFormSchema(fields) {
     return z
         .object({})
@@ -71,11 +60,14 @@ export function WriteFormSection({ section, featureName, translate, hideTitle, o
             }
             if (result.validationBlocked)
                 return;
-            // Field-level issues already surface inline via snapshot.errors (same
-            // GridCellForField/RenderField path RenderEdit uses) — the banner is
-            // only for form-level errors nothing else would show (fw#1901 pattern).
-            const fieldIssues = result.error.details?.fields ?? [];
-            setError(fieldIssues.length === 0 ? dispatcherErrorText(result.error, effectiveTranslate) : null);
+            // Field-level issues surface inline via snapshot.errors (same
+            // GridCellForField/RenderField path RenderEdit uses) — the banner stays
+            // for anything no rendered field can show (`version`, `id`, a root
+            // refine, a hidden field).
+            const issuePaths = (result.error.details?.fields ?? []).map((i) => i.path);
+            setError(hasIssueWithoutVisibleField(issuePaths, section.fields)
+                ? dispatcherErrorText(result.error, effectiveTranslate)
+                : null);
         }
         finally {
             setIsSubmitting(false);
@@ -106,10 +98,10 @@ export function WriteFormSection({ section, featureName, translate, hideTitle, o
         return (_jsx(Card, { options: { framed: false }, slots: {
                 ...(section.description !== undefined && { subtitle: section.description }),
                 headerActions: titleRowActions,
-            }, testId: `write-form-${section.title ?? "section"}`, children: content }));
+            }, testId: `write-form-${section.title ?? section.handler}`, children: content }));
     }
     // Routed through Section's `actions` slot (same mechanism render-edit.tsx
     // uses via Form's `actions`) so the button gets the established right-
     // aligned footer treatment instead of stretching full-width inline.
-    return (_jsx(Section, { ...(section.title !== undefined && { title: section.title }), ...(section.description !== undefined && { subtitle: section.description }), ...(section.icon !== undefined && { icon: section.icon }), actions: titleRowActions, testId: `write-form-${section.title ?? "section"}`, children: content }));
+    return (_jsx(Section, { ...(section.title !== undefined && { title: section.title }), ...(section.description !== undefined && { subtitle: section.description }), ...(section.icon !== undefined && { icon: section.icon }), actions: titleRowActions, testId: `write-form-${section.title ?? section.handler}`, children: content }));
 }